# When must an instance treat GenAI span attributes as unredactable at the collector boundary **Date of Record:** 2026 November 15 **Scope:** Applies to OpenTelemetry Collector pipelines that perform span-level redaction or PII scrubbing on GenAI semantic convention attributes (`gen_ai.*`, `llm.*`, prompt/completion content, tool-call arguments) before export. Does not apply to log-record scrubbing, metric exemplar scrubbing, or redaction performed inside the SDK prior to span creation. ## Core Distinction Redaction is a *transformation of attribute values*. It is not a *transformation of attribute identity*. The boundary failure occurs when a pipeline redacts the *content* of a GenAI attribute but preserves the *key*, the *shape*, and the *cardinality* of the original value in a way that leaks the very information the redaction was meant to remove. Two facts must be held separately: 1. **Value-level redaction** replaces or masks the payload (e.g., `[REDACTED]`, `***`, a tokenized surrogate). 2. **Structure-level leakage** is the residual signal carried by *which* attribute exists, *how long* the surrogate is, *whether* the span has a `gen_ai.completion.0.content` child at all, and *how many* such children appear. A collector that only does (1) while ignoring (2) has not redacted; it has re-encoded. An instance must treat a GenAI span as **unredactable** — and must refuse to export it in redacted form — when the scrubbing transform cannot guarantee that the residual structure is invariant under the original content. ## What Was Observed In a production pipeline (`genai-redact` processor chained before `batch` and an OTLP/gRPC exporter), the following was observed over a 72-hour window: - Prompt bodies were correctly replaced with `[REDACTED]` for spans matching `gen_ai.operation.name == "chat"`. - However, `gen_ai.completion.{i}.content` attributes were emitted with **one attribute per completion choice**, and the presence/absence of `gen_ai.completion.{i}.tool_calls.{j}.function.arguments` was preserved. A downstream consumer could reconstruct *how many tools the model invoked* and *the approximate token length* of each argument from the attribute key set and surrogate padding, even though every value was masked. - A secondary failure: when a span carried `gen_ai.prompt.{i}.content` where `i` exceeded a configurable `max_prompt_index`, the processor silently dropped the attribute. Dropping is not redaction — it is *absence*, which is itself a signal that the prompt had more than `max_prompt_index` turns. The drop was not recorded as a redaction event, so the audit trail claimed "0 redactions" on spans that had in fact been structurally altered. - A third failure: regex-based scrubbers matched on value and replaced with a fixed-length surrogate, but the *original* `gen_ai.request.model` and `gen_ai.usage.prompt_tokens` remained. Because token counts are a near-deterministic function of prompt length for a given model, the masked prompt length was recoverable from `usage.prompt_tokens` to within a few tokens — enough to distinguish candidate prompts in a small candidate set. None of these are value leaks in the naive sense. All three are **invariant violations**: the redaction transform was not a homomorphism from the space of (content, structure) to a space in which structure carries no information about content. ## Condition of Validity A GenAI span may be exported in redacted form **only if** the scrubbing transform satisfies all of the following, verifiable per-span rather than per-pipeline: - **Key-set invariance under content:** the set of attribute keys present after redaction is a function of the span's *schema* (operation name, model family, spec version), not of the span's *content*. If a key exists because a tool was called, the key must exist unconditionally and carry a redacted marker, or the entire tool-call subtree must be elided uniformly with a recorded elision event. - **No silent drops:** any attribute removed for exceeding an index or size bound must emit a redaction/elision record (`redaction.dropped.count`, `redaction.reason`) on the same span. Absence without an event is a leak. - **Correlated-attribute quarantine:** attributes that are deterministic functions of redacted content (`gen_ai.usage.prompt_tokens`, `gen_ai.usage.completion_tokens`, `gen_ai.response.finish_reasons` in low-entropy cases, `gen_ai.request.max_tokens` when tightly coupled to prompt construction) must either be coarsened (bucketed) or the span must be marked unredactable. - **Surrogate length independence:** the surrogate must not encode original length (fixed-width, not length-preserving padding). When any of these cannot be established for a span — for example, because the model or spec version is unknown to the redaction ruleset, or because a custom attribute namespace is present that the ruleset does not enumerate — the span is **unredactable** and must be routed to a quarantine exporter, not the primary OTLP sink. ## Decision Boundary The boundary is not "is PII present?" It is "can the transform prove residual-structure independence for *this* span's attribute graph?" Concretely: - **Redact and export** when the span's attribute key set is fully enumerated by the active ruleset, all content-bearing keys are replaced with fixed-width surrogates, all index-bounded keys are either present-with-marker or elided-with-event, and correlated usage attributes are bucketed or absent. - **Quarantine (do not redact-and-export)** when the span carries any attribute key outside the ruleset's enumeration, when the `gen_ai.operation.name` is unknown, when the spec version is newer than the ruleset's declared coverage, or when a correlated attribute cannot be coarsened without destroying the span's diagnostic value. - **Drop with audit** only as a last resort, and only with an explicit `redaction.action = "drop"` event on a synthetic audit span, because a dropped span is invisible to downstream integrity checks. The common error is to treat "the value matched a PII regex and was replaced" as sufficient. It is not. The boundary is crossed the moment the *shape* of the span is a function of unredacted content. ## Operational Effect Pipelines that ignore this boundary exhibit a characteristic downstream signature: PII scanners on the exported data report clean, while a determined reconstruction attack (attribute-key cardinality + token-count bucketing + choice count) recovers prompt structure and often prompt identity. The failure is silent because every value-level assertion passes. The correct operational posture is to make the redaction processor *fail closed*: if it cannot prove structural invariance for a span, it raises and routes the span to quarantine rather than emitting a redacted-but-leaky copy. The following reference implementation encodes that posture. ```python from __future__ import annotations from dataclasses import dataclass, field from typing import Iterable REDACTED = "[REDACTED]" CORRELATED_USAGE_KEYS = frozenset({ "gen_ai.usage.prompt_tokens", "gen_ai.usage.completion_tokens", }) class UnredactableSpanError(RuntimeError): """Raised when a GenAI span cannot be proven structurally redactable. The span must be routed to quarantine, not exported in redacted form. """ @dataclass(frozen=True) class RedactionRuleset: spec_version: str known_operation_names: frozenset[str] enumerated_keys: frozenset[str] max_prompt_index: int = 32 surrogate_width: int = len(REDACTED) @dataclass class RedactionResult: attributes: dict[str, str] events: list[str] = field(default_factory=list) def _is_content_key(key: str) -> bool: return ( key.startswith("gen_ai.prompt.") or key.startswith("gen_ai.completion.") or key.startswith("gen_ai.tool.") ) and key.endswith((".content", ".arguments")) def redact_genai_span( attributes: dict[str, str], ruleset: RedactionRuleset, ) -> RedactionResult: op = attributes.get("gen_ai.operation.name") if op is None or op not in ruleset.known_operation_names: raise UnredactableSpanError( f"unknown gen_ai.operation.name={op!r}; ruleset " f"{ruleset.spec_version} cannot prove structural invariance" ) unknown = [k for k in attributes if k not in ruleset.enumerated_keys] if unknown: raise UnredactableSpanError( f"attributes outside ruleset enumeration: {sorted(unknown)}" ) out: dict[str, str] = {} events: list[str] = [] for key, value in attributes.items(): if _is_content_key(key): out[key] = REDACTED[: ruleset.surrogate_width] events.append(f"redacted:{key}") continue if key in CORRELATED_USAGE_KEYS: # Coarsen to a power-of-two bucket so token counts cannot # reconstruct prompt length to within a few tokens. try: n = int(value) except ValueError as exc: raise UnredactableSpanError( f"non-integer usage attribute {key}={value!r}" ) from exc bucket = 1 << max(n, 1).bit_length() out[key] = str(bucket) events.append(f"bucketed:{key}:{n}->{bucket}") continue out[key] = value # Index-bound check: any indexed content key beyond the bound must have # produced an explicit elision event, never a silent drop. for key in attributes: if key.startswith("gen_ai.prompt.") and _is_content_key(key): try: idx = int(key.split(".")[2]) except (IndexError, ValueError): continue if idx >= ruleset.max_prompt_index: raise UnredactableSpanError( f"prompt index {idx} exceeds bound " f"{ruleset.max_prompt_index}; elide uniformly or quarantine" ) return RedactionResult(attributes=out, events=events) def redact_batch( spans: Iterable[dict[str, str]], ruleset: RedactionRuleset, ) -> tuple[list[RedactionResult], list[dict[str, str]]]: clean: list[RedactionResult] = [] quarantine: list[dict[str, str]] = [] for span in spans: try: clean.append(redact_genai_span(span, ruleset)) except UnredactableSpanError: quarantine.append(span) return clean, quarantine ```