# os_observatory Manual

This manual explains the architecture, APIs, integration steps, and design rationale of `os_observatory`, a zero-dependency observability toolkit for operating systems.

Contents:
- Overview
- Architecture
- Modules
- Integration (no_std kernels)
- Testing on host
- Safety and performance
- FAQ

## Overview
`os_observatory` aims to make OS instrumentation practical without pulling in external dependencies. It offers text logging to pluggable sinks, low-overhead event tracing, panic reporting, and small memory helpers. Everything is `no_std`-first and documented for docs.rs.

## Architecture
The crate is intentionally small and layered:
- `sink` abstracts output destinations. A lock-free `RingBufferSink` is provided.
- `logging` implements a `Logger` with macros `os_error!`, `os_warn!`, `os_log!`, `os_trace!`.
- `tracer` records compact events into a fixed-capacity circular buffer.
- `panic` emits minimal panic diagnostics via a sink.
- `mem` contains alignment and range helpers.
- `build` exposes compile-time metadata (name, version, optional git SHA).

## Modules
- sink: trait `Sink`, impl `RingBufferSink<N>`, method `write_str(&self, &str) -> usize`.
- logging: `Logger<'a, S: Sink>` with level filtering, macros for convenience.
- tracer: `EventTracer<N>` storing `EventRecord { ts, id, payload0, payload1 }`.
- panic: `report_panic(&S, &PanicInfo)` to format lightweight diagnostics.
- mem: `is_aligned`, `align_up`, `align_down`, `range_fits`, `page` sizes.
- build: `BuildStamp::capture()` returns compile-time constants.

## Integration (no_std)
1. Implement `Sink` for your hardware writer or use `RingBufferSink`.
2. Create `Logger::new(&sink)` and set level.
3. Use logging macros in your code paths.
4. Instantiate `EventTracer<N>` in hot paths to record timings and IDs.
5. In your panic handler, call `panic::report_panic(&sink, info)`.

## Testing on host
Under host tests, prefer using `RingBufferSink` and snapshotting its buffer to assert on outputs. All modules avoid allocation by default and do not require external crates.

## Safety and performance
- Lock-free ring buffers use atomics and avoid blocking in interrupts.
- Tracing records are compact and written with a Release fence for visibility.
- Logging uses `core::fmt::Write` without heap.
- Panic reporting avoids allocations and writes a single line.

## FAQ
Q: Does this crate allocate?
A: No, unless you opt into `alloc` for your own extensions. The core APIs avoid allocation.

Q: Is `std` required?
A: No. The crate is `no_std`-first. `std` can be used in tests if desired.

Q: How do I export tracer data?
A: Call `snapshot(&mut out)` to copy records in oldest-to-newest order.

