# 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.