OBS requirements¶
Logging shall support deferred formatting with string interning in a non-loaded section, decodable from the ELF. Rationale: ADR-009: logging cheap enough to leave on in production. Status: Accepted 2026-10-07 Verification: Test: Trace: SPEC-015 §2 |
Log severity shall be filterable at compile time per module and at runtime per module. Rationale: Zero cost for excluded levels; control in the field for the rest. Status: Accepted 2026-10-07 Verification: Footprint test (excluded calls absent); runtime filter test. Trace: SPEC-015 §2.1 |
ISR logging shall be non-blocking and bounded; drops shall be counted, not hidden. Rationale: A log call must never change timing by blocking. Status: Accepted 2026-10-07 Verification: Test: Trace: SPEC-015 §2.3 |
Log transports shall include UART, SWO/ITM, RTT-like memory channel, USB, retained RAM ring, and network, selected by configuration. Rationale: Products differ in what is wired. Status: Accepted 2026-10-07 Verification: Transport tests per reference board. Trace: SPEC-015 §7 |
Trace points shall compile to nothing when disabled and to a bounded store when enabled. Rationale: Zero-cost opt-out; no unbounded buffers. Status: Accepted 2026-10-07 Verification: Footprint test with trace classes off; overflow test with Trace: SPEC-015 §3.2 |
Trace output shall be CTF with generated metadata; EmbDebug shall not be required to decode it. Rationale: ADR-021. Status: Accepted 2026-10-07 Verification: Babeltrace 2 reads a captured stream in CI. Trace: SPEC-015 §3 |
Trace shall support streaming (probe, UART, network) and snapshot (ring buffer dumped on fault or demand) modes. Rationale: Live analysis and post-mortem need both. Status: Accepted 2026-10-07 Verification: Test: streaming over the memory channel; snapshot dump through the descriptor. Trace: SPEC-015 §3.3 |
The image shall export a versioned debug descriptor sufficient to enumerate threads, states, priorities, stacks, owned locks, partitions, and devices without knowledge of private struct layout. Rationale: ADR-011. Status: Accepted 2026-10-07 Verification: Trace: SPEC-015 §5 |
Worst-case interrupt-masked and scheduler-locked intervals shall be recorded per CPU and per thread with the address of the opener, as a compile-time option. Rationale: ADR-034. Status: Accepted 2026-10-07 Verification: Test: Trace: SPEC-015 §6 |
Thresholds per monitored category shall be configurable to trace, notify, or fault. Rationale: Field-detectable latency violations. Status: Accepted 2026-10-07 Verification: Test: each action triggered by threshold crossing. Trace: SPEC-015 §6 |
Monitor state shall be exported through the debug descriptor and the statistics API. Rationale: Tools and applications read the same numbers. Status: Accepted 2026-10-07 Verification: Descriptor consumer test; Trace: SPEC-015 §5, §6 |
Benchmark results of a release shall be compared with the previous release’s baseline on the same board and configuration; a regression beyond the configured threshold shall fail the release. Rationale: R-003 §4: targets become baselines. Status: Accepted 2026-10-07 Verification: Release pipeline test with an injected regression. Trace: SPEC-015 §8; TEST-012 |
A log record shall be Rationale: Smallest records, host-side formatting, mid-stream resynchronization. Status: Accepted 2026-10-07 Verification: Decoder tests including mid-stream join and drop records; AVR plain-text test. Trace: SPEC-015 §2.2 to §2.5 |
The 1.0 trace event set shall be the catalogue of SPEC-015 §3.1 defined in Rationale: One catalogue keeps every specification’s events decodable by one tool. Status: Accepted 2026-10-07 Verification: Generator golden test; Babeltrace reads every event class. Trace: SPEC-015 §3.1, §3.2 |
Event timestamps shall be 32-bit trace clock ticks with the 64-bit value in packet headers and a CTF clock class declaring the frequency from the hardware description; the tiny profile may use the kernel tick. Rationale: Tools convert to time without guesswork. Status: Accepted 2026-10-07 Verification: Metadata check; Trace Compass displays absolute times. Trace: SPEC-015 §3.4 |
The crash record shall follow the v1 layout of SPEC-015 §4 (header, build id, uptime, reset reason, fault fields, status and general registers with counts, flight recorder tail, CRC-32), written before any recovery action to the retained section or Rationale: FLT-001 made concrete and decodable by Status: Accepted 2026-10-07 Verification: Fault-injection test: record written, survives reset, decodes and symbolizes. Trace: SPEC-015 §4 |
The descriptor shall contain the sections of SPEC-015 §5 (header, types, thread, scheduler, objects, partitions, rings, monitors, arch), be exported at Rationale: OBS-008 made exact. Status: Accepted 2026-10-07 Verification: Trace: SPEC-015 §5 |
The kernel shall offer Rationale: 04 §7.5; ADR-034. Status: Accepted 2026-10-07 Verification: API tests; footprint with statistics off. Trace: SPEC-015 §6 |
Byte-stream transports shall carry COBS frames with a channel byte and CRC-16 (channels 0 log, 1 trace, 2 crash, 3 shell, 4 to 15 application); the memory channel shall export a control block at Rationale: One framing for every stream; probe tooling reuse. Status: Accepted 2026-10-07 Verification: Decoder resynchronization test; RTT-compatible read by an existing probe tool. Trace: SPEC-015 §7 |
Rationale: The decoders are part of the product. Status: Accepted 2026-10-07 Verification: Tool tests including a mismatched build id. Trace: SPEC-015 §10 |
Observability defaults per profile shall be those of SPEC-015 §9: plain-text log and small crash record on tiny, deferred log and snapshot trace on base, streaming trace and partition records on isolated and multicore, host pipe decoding on native; the descriptor shall be present in every profile. Rationale: Footprint where it matters, evidence everywhere. Status: Accepted 2026-10-07 Verification: Configuration review; footprint tests. Trace: SPEC-015 §9 |