33 lines
1.6 KiB
Markdown
33 lines
1.6 KiB
Markdown
# 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]'
|
|
```
|