36 lines
1.8 KiB
Markdown
36 lines
1.8 KiB
Markdown
# Telemetry scrubbing contract (TELEMETRY-OBS-51-002)
|
|
|
|
**Purpose**: define redaction/scrubbing rules for logs/traces/metrics before implementing helpers in `StellaOps.Telemetry.Core`.
|
|
|
|
## Redaction rules
|
|
- Strip or hash PII/credentials: emails, tokens, passwords, secrets, bearer/mTLS cert blobs.
|
|
- Default hash algorithm: SHA-256 hex; include `scrubbed=true` tag.
|
|
- Allowlist fields that remain: `tenant`, `trace_id`, `span_id`, `endpoint`, `result`, `sealed`.
|
|
|
|
## Configuration knobs
|
|
- `Telemetry:Scrub:Enabled` (bool, default true).
|
|
- `Telemetry:Scrub:Sealed` (bool, default false) — when true, force scrubbing and disable external exporters.
|
|
- `Telemetry:Scrub:HashSalt` (string, optional) — per-tenant salt; omit to keep deterministic hashes across deployments.
|
|
- `Telemetry:Scrub:MaxValueLength` (int, default 256) — truncate values beyond this length before hashing.
|
|
|
|
## Logger sink expectations
|
|
- Implement scrubber as `ILogPayloadFilter` injected before sink.
|
|
- Ensure message templates remain intact; only values scrubbed.
|
|
- Preserve structured shape so downstream parsing remains deterministic.
|
|
|
|
## Metrics & traces
|
|
- Never place raw user input into metric/tag values; pass through scrubber before export.
|
|
- Span events must omit payload bodies; include keyed references only.
|
|
|
|
## Auditing
|
|
- When scrubbing occurs, add tag `scrubbed=true` and `scrub_reason` (`pii|secret|length|pattern`).
|
|
- Provide counter `telemetry.scrub.events{tenant,reason}` for observability.
|
|
|
|
## Tests to add with implementation
|
|
- Unit tests for regex-based scrubbing of tokens, emails, URLs with creds.
|
|
- Config-driven tests toggling `Enabled`/`Sealed` modes to ensure exporters are suppressed when sealed.
|
|
- Determinism test: same input yields identical hashed output when salt unset.
|
|
|
|
## Provenance
|
|
- Authored 2025-11-20 to unblock TELEMETRY-OBS-51-002 and downstream 55/56 tasks.
|