OpenTelemetry GenAI Semantic Conventions Redaction & Truncation Invariant

--- description: OpenTelemetry GenAI Semantic Conventions Redaction & Truncation Invariant - Mandates strict deterministic token-level PII/secrets redaction and bounded context-window byte/token truncation prior to mutating OpenTelemetry GenAI spans. All spans implementing gen_ai.prompt and gen_ai.completion attributes must execute sanitization pipelines locally in-process before delegating to span processors, batch exporters, or downstream telemetry aggregators. globs: src/telemetry/**/*.ts, src/observability/**/*.ts, src/llm/**/*.ts, src/instrumentation/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-genai-semantic-conventions-redaction-invariant" --- # OpenTelemetry GenAI Semantic Conventions Redaction & Truncation Invariant > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Exporting raw prompts and completions directly into gen_ai.* attributes without pre-export redaction and bound checks ## System Constraints You are a Principal Software Architect enforcing OpenTelemetry GenAI Semantic Conventions with deterministic in-process PII/secret scrubbing and context-window length capping. Every GenAI prompt and completion capture must pass through a verified, deterministic sanitizer and truncator before mutating span attributes. Raw unredacted strings must never touch the OpenTelemetry tracing pipeline. ## Strict Guidelines - Engineers MUST ALWAYS sanitize gen_ai.prompt.* and gen_ai.completion.* attributes via an in-memory redaction engine (e.g., regex/masking rules for API keys, SSNs, credit cards, emails) BEFORE invoking span.setAttribute(). - Engineers MUST enforce strict context-window byte/character truncation limits (default 4096 bytes or explicit token boundary) with an appended '[TRUNCATED]' marker to prevent trace memory exhaustion. - Engineers MUST NOT disable redaction conditionally based on process.env.NODE_ENV unless explicitly executing in an isolated local mock environment without actual telemetry exports. - Custom SpanProcessors SHOULD serve as a secondary defensive fail-safe to drop or scrub accidentally leaked raw attributes prior to BatchSpanProcessor export. - Services MUST emit a metric counter (e.g., gen_ai.client.redacted_entities_total) whenever sensitive tokens are caught and neutralized within a trace. ## Bad vs Good Implementations ### Naive OpenTelemetry GenAI Span Population vs Deterministic Redacted Implementation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly assigning rawPrompt and completion to gen_ai semantic attributes leaks unredacted PII, API tokens, and credentials to observability vendors and logs. It also risks out-of-memory crashes due to unbounded context payloads. ```typescript import { trace, Span } from '@opentelemetry/api'; const tracer = trace.getTracer('genai-service'); export async function trackInference(rawPrompt: string, callModel: (p: string) => Promise<string>): Promise<string> { return tracer.startActiveSpan('gen_ai.client.inference', async (span: Span) => { try { // CRITICAL VIOLATION: Raw user prompt containing potential PII/secrets // directly assigned to OpenTelemetry semantic attribute without truncation or redaction. span.setAttribute('gen_ai.system', 'openai'); span.setAttribute('gen_ai.request.model', 'gpt-4o'); span.setAttribute('gen_ai.prompt', rawPrompt); const completion = await callModel(rawPrompt); // CRITICAL VIOLATION: Unscrubbed completion output potentially containing // reflected PII or extracted secrets exported downstream. span.setAttribute('gen_ai.completion', completion); return completion; } finally { span.end(); } }); } ``` #### Production Standard (Correct) > **Standard**: Implements deterministic regex-based scrubbing for emails, payment cards, and API secrets alongside byte-bounded truncation before telemetry assignment, guaranteeing that OpenTelemetry GenAI semantic conventions are met without violating data privacy invariants. ```typescript import { trace, Span } from '@opentelemetry/api'; const tracer = trace.getTracer('genai-service'); const MAX_ATTRIBUTE_BYTES = 4096; const PII_PATTERNS: ReadonlyArray<{ pattern: RegExp; mask: string }> = [ { pattern: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, mask: '[REDACTED_EMAIL]' }, { pattern: /\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14})\b/g, mask: '[REDACTED_CARD]' }, { pattern: /(?:Bearer\s+|sk-[a-zA-Z0-9]{20,})/gi, mask: '[REDACTED_SECRET]' } ]; function sanitizeGenAiPayload(payload: string, maxBytes: number = MAX_ATTRIBUTE_BYTES): string { let scrubbed = payload; for (const { pattern, mask } of PII_PATTERNS) { scrubbed = scrubbed.replace(pattern, mask); } const buffer = Buffer.from(scrubbed, 'utf-8'); if (buffer.byteLength > maxBytes) { return buffer.subarray(0, maxBytes).toString('utf-8') + '... [TRUNCATED]'; } return scrubbed; } export async function trackInference(rawPrompt: string, callModel: (p: string) => Promise<string>): Promise<string> { return tracer.startActiveSpan('gen_ai.client.inference', async (span: Span) => { try { span.setAttribute('gen_ai.system', 'openai'); span.setAttribute('gen_ai.request.model', 'gpt-4o'); // Invariant satisfied: deterministic scrubbing and bounded length span.setAttribute('gen_ai.prompt', sanitizeGenAiPayload(rawPrompt)); const completion = await callModel(rawPrompt); span.setAttribute('gen_ai.completion', sanitizeGenAiPayload(completion)); return completion; } finally { span.end(); } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry GenAI Semantic Conventions Redaction & Truncation Invariant

OpenTelemetry GenAI Semantic Conventions Redaction & Truncation Invariant defines an industrial-grade behavioral standard for devops engineering. Mandates strict deterministic token-level PII/secrets redaction and bounded context-window byte/token truncation prior to mutating OpenTelemetry GenAI spans. All spans implementing gen_ai.prompt and gen_ai.completion attributes must execute sanitization pipelines locally in-process before delegating to span processors, batch exporters, or downstream telemetry aggregators. 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 raw prompts and completions directly into gen_ai.* attributes without pre-export redaction and bound checks 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 raw prompts and completions directly into gen_ai.* attributes without pre-export redaction and bound checks	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 sanitize gen_ai.prompt.* and gen_ai.completion.* attributes via an in-memory redaction engine (e.g., regex/masking rules for API keys, SSNs, credit cards, emails) BEFORE invoking span.setAttribute().

Engineers MUST ALWAYS sanitize gen_ai.prompt.* and gen_ai.completion.* attributes via an in-memory redaction engine (e.g., regex/masking rules for API keys, SSNs, credit cards, emails) BEFORE invoking span.setAttribute().

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.