git.stella-ops.org/docs/modules/telemetry/guides/logging.md

Logging Standards (DOCS-OBS-50-003)

Last updated: 2025-12-15

Goals

• Deterministic, structured logs for all services.
• Keep tenant safety and redaction guarantees while enabling search, correlation, and offline analysis.

Log shape (JSON)

Required fields:

• timestamp (UTC ISO-8601)
• tenant, workload (service name), env, region, version
• level (debug|info|warn|error|fatal)
• category (logger/category name), operation (verb/action)
• trace_id, span_id, correlation_id (if external)
• message (concise, no secrets)
• status (ok|error|fault|throttle)
• error.code, error.message (redacted), retryable (bool) when status != ok

Optional but recommended:

• resource (subject id/purl/path when safe), http.method, http.status_code, duration_ms, host, pid, thread.

Offline Kit / air-gap import fields

When emitting logs for Offline Kit import/activation flows, keep field names stable:

• Required scope key: tenant_id
• Common keys: bundle_type, bundle_digest, bundle_path, manifest_version, manifest_created_at
• Force activation keys: force_activate, force_activate_reason
• Outcome keys: result, reason_code, reason_message
• Quarantine keys: quarantine_id, quarantine_path

Redaction rules

• Never log Authorization headers, tokens, passwords, private keys, full request/response bodies.
• Redact to "[redacted]" and add redaction.reason (secret|pii|policy).
• Hash low-cardinality identifiers when needed (sha256 hex) and mark hashed=true.

Determinism & offline posture

• Stable key ordering not required, but field set must be consistent per log type.
• No external enrichment; rely on bundled metadata (service map, tenant labels).
• All times UTC; newline-delimited JSON (NDJSON); LF line endings.

Sampling & rate limits

• Info logs rate-limited per component (default 100/s); warn/error/fatal never sampled.
• Structured audit logs (category=audit) are never sampled and must include actor, action, target, result.

Validation checklist

• Required fields present and non-empty.
• No secrets/PII; redaction markers recorded.
• Correlation fields (trace_id, span_id) set when spans exist.
• Log level matches outcome (errors use warn/error/fatal only).