stella CLI — Observability Guide

Audience: operators and on-call engineers who pull service health, traces, and logs from the terminal, including in sealed/air-gapped environments.

The stella obs commands surface StellaOps telemetry — service health, distributed traces, and logs — as deterministic, machine-readable output suitable for scripting and incident response. The CLI forwards what the API returns; it does not redact server-side.

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 the correlated trace if the server supports it; prints correlation and 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 the Output and exit codes contract (not found → 4; offline violation → 5).
• Correlation IDs and trace IDs are echoed on stderr in verbose mode for scripting and 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-1f4c560d8e2a --output json | jq '.spans[0]'

Related docs

• Output and exit codes — exit-code and determinism contract.
• CLI command reference — the full stella verb tree.