Wiki · Concept · Last reviewed June 25, 2026

OpenTelemetry Transformation Language

OpenTelemetry Transformation Language, usually shortened to OTTL, is a small domain-specific language for processing telemetry with OpenTelemetry-native concepts. In AI systems, it can turn an observability pipeline into a programmable policy layer for redaction, enrichment, filtering, routing, sampling conditions, and audit preservation.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: OpenTelemetry, OTTL, observability, AI agents, telemetry governance

Definition

OpenTelemetry Transformation Language is part of the OpenTelemetry Collector Contrib project. Its upstream README describes it as a small programming language for processing data with OpenTelemetry-native concepts and constructs. An OTTL statement has a function that transforms telemetry and may also have a condition that decides whether the function executes. The language exposes paths into telemetry data, such as span attributes, log bodies, resource attributes, metric datapoints, and other signal-specific fields.

That makes OTTL different from an application logging convention. It is not the event schema itself, and it is not the backend where traces, metrics, or logs are stored. It is policy code that runs while telemetry is moving through a collector component. The same application event can become safer, cheaper, clearer, or less evidentiary depending on what OTTL does to it before export.

Where It Runs

The OpenTelemetry documentation frames the OpenTelemetry Collector as a place to transform data before it is sent to a vendor or another system, often for data quality, governance, cost, and security reasons. The Collector processor list currently includes the Transform Processor, the Filter Processor, the Tail Sampling Processor, and the Routing Connector, each with different roles in a pipeline.

OTTL appears across that family. The OTTL README says to use the transform processor to modify data, the filter processor to remove data, the tail sampling processor to select spans for sampling, and the routing connector to route data between pipelines. The Transform Processor README says the processor modifies telemetry by configuration using OTTL; its component status in the Collector docs is beta for traces, metrics, and logs. The upstream OTTL README also marks traces, metrics, and logs as beta, while profile support is still in development.

AI Agent Telemetry

For AI Agents, telemetry is no longer only request latency and error count. A useful record may include model route, prompt template version, retrieval source identifiers, tool-call name, delegated action, authorization context, policy decision, token use, evaluator result, user-visible response, and incident label. That record can help engineers debug a failure and help reviewers reconstruct what happened.

OTTL matters because those fields are unevenly safe. A trace may need a stable model name, route, task identifier, and tool result status. It may not need the raw prompt, secret-bearing tool payload, complete document text, personal identifier, or opaque vendor metadata. OTTL can normalize names, add deployment context, delete fields, cap attribute size, rewrite sensitive patterns, and separate evidence streams before the data reaches long-term storage.

Governance Use

The practical governance use is controlled transformation at the pipeline boundary. Teams can keep high-value correlation fields while reducing exposure. They can tag a model gateway span with a review class, move a noisy attribute into a less expensive store, keep only approved resource keys, or route incident-class traces to a restricted backend. This is not a replacement for application-level minimization, but it gives platform teams a second chance to enforce policy across many services.

OTTL also makes policy reviewable. A natural-language promise such as "we redact prompts" is weak unless the actual processor configuration shows which fields are removed, transformed, preserved, and exported. A serious review should inspect the OTTL statements, the collector version, the enabled processors, the export destinations, and the tests that prove the rules behave on realistic AI traffic.

Limits

OTTL can damage evidence. The Transform Processor warning section is explicit that users can modify all aspects of telemetry and should understand their data. The documented risks include unsound metric transformations, metric identity conflict, and orphaned telemetry if identifiers such as trace IDs, span IDs, or parent span IDs are changed. The processor also has error modes; a propagated error can result in payloads being dropped from the collector.

Security limits are just as important. OpenTelemetry's sensitive-data guidance says implementers are responsible for understanding and protecting the telemetry they emit or collect, and it recommends data minimization. OTTL can help implement that discipline, but it can also create false confidence if it is untested, too broad, too late in the pipeline, or bypassed by another exporter.

Minimum Record

An AI deployment using OTTL should keep a versioned governance record for each collector pipeline. That record should name the collector distribution and version, component versions, signal types, statement groups, error modes, OTTL contexts, fields read, fields written, fields deleted, route destinations, sampling effects, test fixtures, rollback owner, and privacy reviewer. It should also state whether raw prompts, documents, embeddings, user identifiers, tool payloads, or credentials are expected to appear before transformation.

Source Discipline

Use OpenTelemetry project documentation for the language, processor behavior, component status, sensitive-data guidance, and collector pipeline claims. Use vendor guides only for vendor-specific configuration or backend behavior. Treat every OTTL rule as executable governance: review it like production code, test it on representative traces, and confirm that the downstream store contains what the policy says it contains.

Spiralist Reading

OTTL is a grammar for deciding what the machine remembers about itself. It can protect people from unnecessary exposure, or it can polish surveillance into a clean dashboard. The Spiralist discipline is to make transformation legible: preserve enough evidence for accountability, delete what should not become institutional memory, and never confuse a neat trace with a just system.

Sources

Return to Wiki