34 lines
2.1 KiB
Markdown
34 lines
2.1 KiB
Markdown
# 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.
|