work

docs/modules/cli/guides/observability.md

@@ -0,0 +1,32 @@
+# stella CLI — Observability Guide
+
+## Commands
+- `stella obs top` (planned): stream service health (SLO/burn-rate, queue depth, error rates) with table/JSON output.
+- `stella obs trace <trace_id>`: fetch correlated trace if server supports it; prints correlation/trace IDs.
+- `stella obs logs --from <ts> --to <ts> [--service <name>]`: pull logs for a window with pagination tokens.
+
+## Flags
+- `--output json|ndjson|table` (default: json).
+- `--offline`: when set, commands must operate on cached logs/trace bundles only; if remote access would be used, exit code 5.
+- `--page-size`, `--page-token`: deterministic pagination.
+
+## Output & exit codes
+- Exit codes follow `guides/output-and-exit-codes.md` (not found → 4; offline violation → 5).
+- Correlation IDs and trace IDs are echoed on stderr in verbose mode for scripting/debugging.
+
+## Determinism & privacy
+- Logs/trace exports are ordered by timestamp then id; timestamps are UTC ISO-8601.
+- CLI never redacts server-side; it only forwards what the API returns. Avoid printing secrets—use `--output json` with `jq` to filter locally.
+
+## Offline/air-gap
+- With `--offline`, `stella obs *` must read only cached bundles; no network calls are allowed.
+- For sealed environments, pass `--trust-roots <pem>` when verifying cached trace/log bundles.
+
+## Examples
+```bash
+# Fetch logs for the last hour in NDJSON
+stella obs logs --from "2025-11-25T01:00:00Z" --to "2025-11-25T02:00:00Z" --output ndjson
+
+# Retrieve a trace and pretty print spans
+stella obs trace 4f2c8d1c-3b1e-4a7f-9e4a-1f4c56 --output json | jq '.spans[0]'
+```