Add high-cardinality telemetry protection: label budgets, redaction and log sampling (#214)

[OkeyAmy]

What

Closes #214 with a small, well-tested vertical slice: a TelemetryGuard sitting between callers and TelemetryService's telemetry sinks.

• Unsafe labels are rejected as-is — every metric label value is normalized (tokens/secrets → __sensitive__, UUID/email/address/hash identifiers → placeholders, charset bounded, 64-char cap) and counted against a per metric :: label cardinality budget (default 128). Values beyond the budget collapse into __over_budget__; observations are never dropped, so totals stay exact. Every collapse increments trellis_telemetry_label_rejections_total{metric,label,reason} so operators can find the leaking caller.
• Redaction on the log path — the serialized log line runs through the existing sensitive-data mask with length-capped free-text fields and a 2 KB metadata cap; the event returned to callers keeps its original values.
• Deterministic sampling — non-failure log lines are sampled at TELEMETRY_LOG_SAMPLE_RATE (default 1 = previous behaviour); failures always emit; suppressed lines are counted in trellis_telemetry_log_events_suppressed_total{kind}. Metrics series are never sampled.

Why

recordOperation labels come from caller-influenced sources — the @Telemetry decorator reads actor_type from token claims and error_code from thrown errors. One Prometheus series per distinct value means unbounded memory growth and unusable dashboards under abusive input; logs had no volume or payload control at all.

Impact

• New: src/observability/telemetry-guard.ts + spec (18 tests)
• Changed: src/observability/telemetry.service.ts (guard wiring, sampled/capped log emission, guarded funnel logging) + spec (6 new integration tests; all 15 pre-existing tests unchanged and green)
• New: docs/TELEMETRY_PROTECTION.md — configuration, operational edge cases, failure modes, rollback/recovery

Compatibility

Public APIs and event schemas are unchanged. Default configuration (budget 128, rate 1) is behaviour-compatible: legitimate operation/actor/error values pass through verbatim, so existing dashboards and alerts keep matching. Gauges are deliberately not routed through the guard (stateful budget vs inc/dec pairing) — documented as a follow-up, along with the per-request timing log line.

Verification

• npx jest src/observability/telemetry.service.spec.ts src/observability/telemetry-guard.spec.ts → 39/39 green, repeated ×3
• Observability directory plus external consumers (submission-verifier, reconciliation, monitoring): green except two suites that fail identically on upstream/main (missing enums/sensitive-action-event-type.enum — pre-existing baseline red, verified via git stash)
• npx tsc --noEmit filtered to observability/ paths → clean (repo baseline has pre-existing errors elsewhere)

[drips-wave]

@OkeyAmy Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[github-actions]

Code Review & Auto-Merge — @dorismaduegbunam 🚀

Thank you @OkeyAmy for your contribution!

• PR Title: Add high-cardinality telemetry protection: label budgets, redaction and log sampling (Trellis API: Add high-cardinality telemetry protection with redaction and sampling rules #214)
• Author: @OkeyAmy
• Branch: feat/214-telemetry-protection -> main
• Linked Issues: Closes Trellis API: Add high-cardinality telemetry protection with redaction and sampling rules #214
• Status: Approved & Merged into main.

Verified code changes and repository requirements. Merging pull request.