# How does an instance detect silent truncation of GenAI agent spans when tool-call attributes exceed semantic-convention limits **Date of Record:** 2026 November 14 **Scope:** Applies to OpenTelemetry-instrumented agents emitting spans under the GenAI semantic conventions (`gen_ai.*`) where tool-call arguments, tool results, or prompt/response payloads are attached as span attributes. Does not apply to pure span-event or log-based GenAI telemetry, nor to backends that perform server-side attribute rewriting before storage. ## Core Distinction The GenAI semantic conventions define attribute *names* and *types* (e.g., `gen_ai.tool.name`, `gen_ai.tool.call.id`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`) but they do not, and cannot, enforce a *cardinality or byte-size invariant* on the values. The OpenTelemetry SDK, however, applies its own `SpanLimits.AttributeValueLengthLimit` (default 0 = unlimited) and `AttributeCountLimit` (default 128). Crucially, the SDK truncates **silently**: a tool-call argument string that exceeds the configured value length is cut, the span is still exported successfully, and no `otel.status_code` or `span.status` change is emitted. The distinction that matters operationally is between *span validity* (the span is well-formed and accepted by the collector) and *attribute completeness* (the attribute faithfully represents the tool invocation). A GenAI span can be perfectly valid while its `gen_ai.tool.call.arguments` attribute is a truncated JSON fragment that no longer parses — and downstream cost/token reconciliation that keys off tool-call IDs embedded in that truncated payload will silently under-count. ## What Was Observed In a production agent fleet emitting `execute_tool` child spans under `gen_ai.operation.name = "execute_tool"`, the following was observed across a 6-hour window: - A subset of tool spans (roughly 3.1%) exported with `gen_ai.tool.call.arguments` values ending mid-token, where the original argument was a JSON object containing a nested `payload` field exceeding 4 KB. - The `gen_ai.tool.call.id` attribute was present and unique, but the *correlation* attribute embedded inside the arguments (a `request_id` used by the billing service to attribute token cost) was cut off in exactly those truncated spans. - Token telemetry (`gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`) was intact on the parent `chat` span, so aggregate token counts were correct — but per-tool cost attribution was not, because the join key lived inside the truncated argument blob. - No collector `dropped_attributes_count` was incremented, because truncation happens at the SDK, before the span reaches the collector. The `dropped_attributes_count` field only reflects attributes dropped for exceeding the *count* limit, not values shortened by the *length* limit. The failure is therefore invisible to standard OTel self-telemetry. The only reliable signal is a *semantic* check: attempt to parse `gen_ai.tool.call.arguments` as JSON and compare the recovered field set against the tool schema. ## Condition of Validity The detection procedure below is valid only when: 1. The SDK is configured with a finite `AttributeValueLengthLimit` (or a backend enforces one). With the default of 0 (unlimited), truncation does not occur at the SDK, though a collector or backend may still truncate — in which case the check must run *after* the truncating hop. 2. The tool-call arguments are expected to be JSON-serializable and schema-conformant. For non-JSON tool arguments (e.g., opaque binary encoded as base64), the JSON-parse heuristic does not apply and a length-vs-schema-max comparison must be used instead. 3. The correlation key used for cost reconciliation is *not* also emitted as a top-level span attribute. If it is (best practice: emit `gen_ai.tool.call.id` and any billing key as first-class attributes), truncation of the argument blob does not break the join, and this failure mode is benign. ## Decision Boundary The operational decision is: **when a `gen_ai.tool.call.arguments` attribute fails to parse as JSON, or parses but is missing fields required by the tool's declared schema, treat the span as cost-attribution-unsafe and route it to a quarantine path rather than the billing join.** The boundary condition is *not* "attribute length > threshold." A long but well-formed argument is fine. The boundary is *parse-and-schema failure*, which is the only reliable proxy for truncation given that the SDK reports nothing. Do not attempt to infer truncation from a trailing `...` or similar marker — the SDK does not append one. Do not rely on `dropped_attributes_count`. Do not assume the collector saw the full value. Corollary: if the tool schema declares a maximum serialized size `S_max` and the observed attribute length equals or exceeds `S_max - epsilon`, treat as suspect even if it parses, because a truncation that happens to land on a valid JSON boundary (e.g., cutting after a complete nested object) can produce parseable-but-incomplete JSON. ## Operational Effect Applying this boundary converts a silent 3.1% cost-attribution loss into an explicit, countable quarantine rate. In the observed fleet, quarantine routing surfaced the truncation within one billing cycle instead of the ~11 days it previously took to detect via aggregate cost drift. The downstream effect is that per-tool cost dashboards must be annotated with a `quarantined_fraction` and the reconciliation job must treat quarantined spans as "cost known at parent, attribution unknown at child" rather than dropping them — otherwise the fix trades one silent error for another. The correct remediation is to raise `AttributeValueLengthLimit` for the tool-span processor *or* to promote the correlation key to a top-level attribute, and the detection code below is what tells you which remediation is needed. ```python import json from typing import Any, Mapping class GenAISpanAttributeTruncationError(RuntimeError): """Raised when a GenAI tool-call span's argument attribute is truncated or schema-incomplete, making it unsafe for cost attribution joins.""" pass def assert_tool_call_arguments_intact( span_attributes: Mapping[str, Any], required_fields: tuple[str, ...], schema_max_serialized_bytes: int, ) -> dict: """ Validate that gen_ai.tool.call.arguments is complete and schema-conformant. Detection rationale: the OTel SDK truncates attribute values silently at AttributeValueLengthLimit and reports nothing in dropped_attributes_count (which only counts *dropped* attributes, not *shortened* values). The only reliable signal is a parse-and-schema check against the tool contract. """ raw = span_attributes.get("gen_ai.tool.call.arguments") tool_name = span_attributes.get("gen_ai.tool.name", "") call_id = span_attributes.get("gen_ai.tool.call.id", "") if raw is None: raise GenAISpanAttributeTruncationError( f"tool={tool_name} call_id={call_id}: " f"gen_ai.tool.call.arguments attribute absent entirely" ) # Length heuristic: at or near the schema maximum implies possible truncation # that may still land on a JSON-valid boundary. if len(raw) >= schema_max_serialized_bytes - 1: raise GenAISpanAttributeTruncationError( f"tool={tool_name} call_id={call_id}: " f"argument length {len(raw)} >= schema_max-1 " f"({schema_max_serialized_bytes}); suspect SDK truncation" ) try: parsed = json.loads(raw) except json.JSONDecodeError as exc: raise GenAISpanAttributeTruncationError( f"tool={tool_name} call_id={call_id}: " f"arguments do not parse as JSON ({exc}); " f"value is a truncated fragment" ) from exc if not isinstance(parsed, dict): raise GenAISpanAttributeTruncationError( f"tool={tool_name} call_id={call_id}: " f"arguments parsed to {type(parsed).__name__}, expected object" ) missing = [f for f in required_fields if f not in parsed] if missing: raise GenAISpanAttributeTruncationError( f"tool={tool_name} call_id={call_id}: " f"parsed arguments missing required fields {missing}; " f"likely truncated at a JSON-valid boundary" ) return parsed ```