OpenTelemetry GenAI Semantic Conventions Cardinality and Boundary Redaction Guardrail

--- description: OpenTelemetry GenAI Semantic Conventions Cardinality and Boundary Redaction Guardrail - Enforces OpenTelemetry GenAI semantic conventions by strictly prohibiting unbounded dynamic metadata and prompt text inside metric dimensions while mandating client-side PII redaction and payload truncation on span attributes. Prevents OpenTelemetry Collector buffer memory exhaustion, catastrophic TSDB index explosion, and telemetry privacy breaches. globs: src/**/telemetry/**/*.{ts,js,py}, src/**/instrumentation/**/*.{ts,js,py}, src/**/llm/**/*.{ts,js,py}, collector/**/*.{yaml,yml} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-genai-cardinality-pii-guardrail" --- # OpenTelemetry GenAI Semantic Conventions Cardinality and Boundary Redaction Guardrail > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Attaching Raw Prompts, PII, or Dynamic Session Identifiers to Metric Dimensions and Unsanitized Spans ## System Constraints You are a Principal Observability and Infrastructure Architect enforcing OpenTelemetry GenAI Semantic Conventions (v1.26.0+). Your mandate is to eliminate high-cardinality metric dimensions and prevent sensitive prompt leakage at the OTel instrumentation boundary. Reject any code that passes raw prompts, completions, session IDs, or user tokens as metric labels or unredacted trace attributes. ## Strict Guidelines - Engineers MUST NEVER record raw user prompts, completion strings, session IDs, or IP addresses as OpenTelemetry Metric attributes/labels. - Engineers MUST restrict GenAI metric dimensions strictly to low-cardinality semantic attributes: 'gen_ai.system', 'gen_ai.request.model', 'gen_ai.response.model', and standardized 'error.type'. - Telemetry components capturing 'gen_ai.prompt' or 'gen_ai.completion' on Traces MUST execute synchronous client-side PII scrubbing and enforce a hard character truncation ceiling (e.g., maximum 2048 characters) before span attachment. - Engineers MUST record token consumption ('gen_ai.usage.input_tokens', 'gen_ai.usage.output_tokens') strictly as numeric values within Histograms or Span Attributes, NEVER as categorical metric dimensions. - Services MUST configure OpenTelemetry Collector pipelines with 'memory_limiter' and 'transform' or 'redaction' processors to fail-safe against client-side guardrail bypasses. ## Bad vs Good Implementations ### Instrumenting GenAI Model Invocations with OTel Metric and Span Safety #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Attaching dynamic user IDs, prompt snippets, and response IDs as metric labels causes an exponential cardinality explosion, degrading the TSDB and OTel Collector. Attaching raw prompt payloads without PII redaction or length bounding risks compliance violations and out-of-memory errors on trace exporters. ```typescript import { trace, metrics } from '@opentelemetry/api'; const tracer = trace.getTracer('llm-service'); const tokenMeter = metrics.getMeter('llm-service'); const tokenCounter = tokenMeter.createCounter('genai.tokens.total'); export async function executePrompt(userId: string, prompt: string, model: string) { return tracer.startActiveSpan('llm_call', async (span) => { // ANTI-PATTERN: Emitting raw prompt with potential PII directly onto span span.setAttribute('gen_ai.prompt', prompt); span.setAttribute('user.id', userId); const response = await callLlmProvider({ model, prompt }); // ANTI-PATTERN: High-cardinality metric attributes (prompt text & user ID as dimensions) // This will quickly crash Prometheus/TSDB indexing pipelines tokenCounter.add(response.usage.totalTokens, { 'gen_ai.model': model, 'user.id': userId, 'prompt.snippet': prompt.slice(0, 50), 'response.id': response.id }); span.end(); return response; }); } ``` #### Production Standard (Correct) > **Standard**: Adheres strictly to OpenTelemetry GenAI Semantic Conventions. Metric dimensions are locked to bounded categoricals ('gen_ai.system', 'gen_ai.request.model', 'gen_ai.token.type'). Prompts are scrubbed of PII and truncated before being attached as span events rather than metric labels, preserving both telemetry integrity and TSDB stability. ```typescript import { trace, metrics, SpanStatusCode } from '@opentelemetry/api'; import { SEMATTRS_GEN_AI_SYSTEM, SEMATTRS_GEN_AI_REQUEST_MODEL } from '@opentelemetry/semantic-conventions'; const tracer = trace.getTracer('llm-service', '1.0.0'); const meter = metrics.getMeter('llm-service', '1.0.0'); const tokenHistogram = meter.createHistogram('gen_ai.client.token.usage', { description: 'Measures token distribution for GenAI operations.', unit: '{token}' }); const MAX_PROMPT_CHARS = 2048; const PII_REGEX = /[\w.-]+@[\w.-]+\.[A-Za-z]{2,}|\b\d{3}-\d{2}-\d{4}\b/g; function sanitizePayload(raw: string): string { return raw.replace(PII_REGEX, '[REDACTED]').slice(0, MAX_PROMPT_CHARS); } export async function executePrompt(userId: string, prompt: string, model: string) { return tracer.startActiveSpan('gen_ai.client.operation', async (span) => { try { span.setAttribute('gen_ai.system', 'anthropic'); span.setAttribute('gen_ai.request.model', model); // Enforce client-side sanitization and length boundary const sanitizedPrompt = sanitizePayload(prompt); span.addEvent('gen_ai.content.prompt', { 'gen_ai.prompt.sanitized': sanitizedPrompt }); const response = await callLlmProvider({ model, prompt }); span.setAttribute('gen_ai.response.model', response.model); span.setAttribute('gen_ai.usage.input_tokens', response.usage.inputTokens); span.setAttribute('gen_ai.usage.output_tokens', response.usage.outputTokens); // SAFE: Only static, low-cardinality semantic dimensions applied to metrics tokenHistogram.record(response.usage.inputTokens, { 'gen_ai.system': 'anthropic', 'gen_ai.request.model': model, 'gen_ai.token.type': 'input' }); span.setStatus({ code: SpanStatusCode.OK }); return response; } catch (error) { span.recordException(error as Error); span.setStatus({ code: SpanStatusCode.ERROR, message: (error as Error).message }); throw error; } finally { span.end(); } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry GenAI Semantic Conventions Cardinality and Boundary Redaction Guardrail

OpenTelemetry GenAI Semantic Conventions Cardinality and Boundary Redaction Guardrail defines an industrial-grade behavioral standard for devops engineering. Enforces OpenTelemetry GenAI semantic conventions by strictly prohibiting unbounded dynamic metadata and prompt text inside metric dimensions while mandating client-side PII redaction and payload truncation on span attributes. Prevents OpenTelemetry Collector buffer memory exhaustion, catastrophic TSDB index explosion, and telemetry privacy breaches. 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: Attaching Raw Prompts, PII, or Dynamic Session Identifiers to Metric Dimensions and Unsanitized Spans 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	Attaching Raw Prompts, PII, or Dynamic Session Identifiers to Metric Dimensions and Unsanitized Spans	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 NEVER record raw user prompts, completion strings, session IDs, or IP addresses as OpenTelemetry Metric attributes/labels.

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.