git.stella-ops.org/docs/modules/cli/guides/observability.md

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

# 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]'