stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
49922dff5ad4435420dac177e832ba4290ceaea9
git.stella-ops.org/docs/observability/telemetry-sealed-56-001.md
master 10212d67c0
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
api-governance / spectral-lint (push) Has been cancelled
Details
Refactor code structure for improved readability and maintainability; removed redundant code blocks and optimized function calls.
2025-11-20 07:50:52 +02:00

2.1 KiB
Raw Blame History

Sealed-mode telemetry helpers (TELEMETRY-OBS-56-001 prep)

Objective

Define behavior and configuration for telemetry when Sealed=true, ensuring no external egress while preserving deterministic local traces/metrics for audits.

Requirements

  • Disable external OTLP/exporters automatically when sealed; fallback to in-memory or file OTLP (telemetry-sealed.otlp) with bounded size (default 10 MB, ring buffer).
  • Add tag sealed=true to all spans/metrics/logs; suppress exemplars.
  • Force scrubbing: treat Scrub.Sealed=true regardless of default settings.
  • Sampling: cap to 10% max in sealed mode unless CLI incident toggle raises it (see CLI-OBS-12-001 contract); ceiling 100% with explicit override Telemetry:Sealed:MaxSamplingPercent.
  • Clock source: require monotonic clock for duration; emit warning if system clock skew detected >500ms.

Configuration keys

  • Telemetry:Sealed:Enabled (bool) — driven by host; when true activate sealed behavior.
  • Telemetry:Sealed:Exporter (enum memory|file) — default file.
  • Telemetry:Sealed:FilePath (string) — default ./logs/telemetry-sealed.otlp.
  • Telemetry:Sealed:MaxBytes (int) — default 10_485_760 (10 MB).
  • Telemetry:Sealed:MaxSamplingPercent (int) — default 10.
  • Derived flag Telemetry:Sealed:EffectiveIncidentMode (read-only) exposes if incident-mode override lifted sampling ceiling.

File exporter format

  • OTLP binary, append-only, deterministic ordering by enqueue time.
  • Rotate when exceeding MaxBytes using suffix .1, .2 capped to 3 files; oldest dropped.
  • Permissions 0600 by default; fail-start if path is world-readable.

Validation tests to implement with 56-001

  • Unit: sealed mode forces exporter swap and tags sealed=true, scrubbed=true.
  • Unit: sampling capped at max percent unless incident override set.
  • Unit: file exporter rotates deterministically and enforces 0600 perms.
  • Integration: sealed + incident mode together still block external exporters and honor scrub rules.

Provenance

  • Authored 2025-11-20 to satisfy PREP-TELEMETRY-OBS-56-001 and unblock implementation.