OpenTelemetry OTTL In-Flight PII Redaction and Sanitization Guardrails

--- description: OpenTelemetry OTTL In-Flight PII Redaction and Sanitization Guardrails - Enforces strict, deterministic OpenTelemetry Transformation Language (OTTL) statements within the collector transform processor to redact and hash sensitive telemetry attributes at ingestion. Guarantees regulatory compliance (GDPR, HIPAA, PCI-DSS) by scrubbing high-entropy credentials, tokens, session cookies, and personal identifiers before export into downline distributed trace and log backends without degrading collector throughput. globs: **/collector.yaml, **/otelcol-config*.yaml, **/otel-collector*.yaml, **/otel/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-ottl-in-flight-pii-redaction-standard" --- # OpenTelemetry OTTL In-Flight PII Redaction and Sanitization Guardrails > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Exporting Unscrubbed Telemetry Payloads or Relying on Client-Side Ad-Hoc Masking ## System Constraints You are a Principal Observability and Security Architect enforcing OpenTelemetry Transform Processor (OTel OTTL) In-Flight PII Redaction Standards. You must mandate deterministic, zero-allocation-focused OTTL rules directly inside OpenTelemetry Collector pipelines. Ensure all trace, metric, and log contexts scrub sensitive HTTP headers, query strings, and body attributes using optimized built-in OTTL functions (replace_all_patterns, SHA256, delete_key) before payloads reach memory-caching exporters or external SaaS backends. ## Strict Guidelines - Engineers MUST ALWAYS configure transform processors using specific contexts ('trace', 'log', 'metric') rather than ambiguous wildcard evaluations. - Engineers MUST NOT rely on client-side application code alone for PII masking; sanitization MUST occur at the ingestion collector boundary before multi-tenant persistence. - Collector pipelines MUST scrub or SHA256-hash standard high-risk HTTP headers ('authorization', 'cookie', 'set-cookie', 'x-api-key') using OTTL statements prior to pipeline export. - Regex replacement statements MUST be bounded and non-catastrophic to prevent CPU starvation and backpressure degradation in high-throughput collector pipelines. - Engineers MUST use 'delete_key' or 'replace_pattern' exclusively within the 'transform' processor rather than deprecated attributes processors or raw regex exporters. - OTTL error modes MUST be explicitly declared as 'error_mode: ignore' or 'error_mode: propagate' based on strictness; production environments MUST default to 'error_mode: ignore' on parsing while logging redaction metric counters to avoid pipeline drops. ## Bad vs Good Implementations ### Naive Unscrubbed Pipeline vs. Hardened OTTL In-Flight Sanitization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Bypasses in-flight redaction completely. Telemetry payloads containing Authorization tokens, Session IDs, and consumer emails pass unredacted to external storage, violating PCI-DSS and GDPR data minimization requirements. ```yaml processors: batch: send_batch_size: 8192 timeout: 1s pipelines: traces: receivers: [otlp] # Invariant violation: No transform processor attached. # Raw headers (Authorization: Bearer <jwt>) and user emails in attributes # leak straight to unencrypted backends and third-party SaaS vendors. processors: [batch] exporters: [otlp/jaeger, otlp/datadog] ``` #### Production Standard (Correct) > **Standard**: Implements an explicit transform processor executing deterministic OTTL statements across span and log contexts. Scrubbing occurs before batching and export, dropping sensitive credentials, hashing user IDs with SHA256, and sanitizing embedded email addresses. ```yaml processors: transform/pii_scrubber: error_mode: ignore trace_statements: - context: span statements: # Drop sensitive authentication and session attributes entirely - delete_key(attributes, "http.request.header.authorization") - delete_key(attributes, "http.request.header.cookie") - delete_key(attributes, "http.response.header.set-cookie") # Redact embedded bearer tokens within general URL or query strings - replace_pattern(attributes["http.target"], "(?i)bearer\\s+[a-zA-Z0-9_\\-\\.]+.*", "[REDACTED_TOKEN]") # Anonymize direct PII while preserving uniqueness for cardinality and troubleshooting - set(attributes["user.id_hash"], SHA256(attributes["enduser.id"])) where attributes["enduser.id"] != nil - delete_key(attributes, "enduser.id") log_statements: - context: log statements: # Redact email addresses within log bodies using bounded regex - replace_pattern(body, "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}", "[REDACTED_EMAIL]") batch: send_batch_size: 8192 timeout: 1s pipelines: traces: receivers: [otlp] processors: [transform/pii_scrubber, batch] exporters: [otlp/jaeger, otlp/datadog] logs: receivers: [otlp] processors: [transform/pii_scrubber, batch] exporters: [otlp/datadog] ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry OTTL In-Flight PII Redaction and Sanitization Guardrails

OpenTelemetry OTTL In-Flight PII Redaction and Sanitization Guardrails defines an industrial-grade behavioral standard for devops engineering. Enforces strict, deterministic OpenTelemetry Transformation Language (OTTL) statements within the collector transform processor to redact and hash sensitive telemetry attributes at ingestion. Guarantees regulatory compliance (GDPR, HIPAA, PCI-DSS) by scrubbing high-entropy credentials, tokens, session cookies, and personal identifiers before export into downline distributed trace and log backends without degrading collector throughput. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Exporting Unscrubbed Telemetry Payloads or Relying on Client-Side Ad-Hoc Masking Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Exporting Unscrubbed Telemetry Payloads or Relying on Client-Side Ad-Hoc Masking	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS configure transform processors using specific contexts ('trace', 'log', 'metric') rather than ambiguous wildcard evaluations.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.