git.stella-ops.org/docs/observability/telemetry-scrub-51-002.md

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.