Telemetry scrubbing contract (TELEMETRY-OBS-51-002)

Audience: developers implementing or reviewing the scrubbing helpers in StellaOps.Telemetry.Core.
Status: contract specification — read alongside the redaction processor in src/Telemetry/.

Purpose: define the redaction and scrubbing rules applied to Stella Ops logs, traces, and metrics before they are exported.

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.

Telemetry standards — the platform-wide scrubbing policy and redaction override procedure.
Propagation contract (TELEMETRY-OBS-51-001) — the context fields that pass through this scrubber.
Sealed-mode helpers (TELEMETRY-OBS-56-001) — sealed mode forces scrubbing on regardless of defaults.

Provenance

Authored 2025-11-20 to unblock TELEMETRY-OBS-51-002 and the downstream 55/56 tasks.