otel-ottl

OpenTelemetry Transformation Language (OTTL)

Components that use OTTL

OTTL is not limited to the transform and filter processors. Processors (transform, filter, attributes, span, tailsampling, cumulativetodelta, logdedup, lookup), connectors (routing, count, sum, signaltometrics), and the hostmetrics receiver all accept OTTL expressions. See components for the full list with use cases.

OTTL syntax

Path expressions

Navigate telemetry data using dot notation:

span.name
span.attributes["http.method"]
resource.attributes["service.name"]

Contexts (first path segment): resource, scope, span, spanevent, metric, datapoint, log.

Enumerations

Use int64 constants for enumeration fields:

span.status.code == STATUS_CODE_ERROR
span.kind == SPAN_KIND_SERVER

Operators

Assignment: = — Comparison: ==, !=, >, <, >=, <= — Logical: and, or, not

Functions

Converters (uppercase, return values):

ToUpperCase(span.attributes["http.request.method"])
Substring(log.body.string, 0, 1024)
Concat(["prefix", span.attributes["request.id"]], "-")
IsMatch(metric.name, "^k8s\\..*$")

Editors (lowercase, modify data in-place):

set(span.attributes["region"], "us-east-1")
delete_key(resource.attributes, "internal.key")
limit(log.attributes, 10, [])

See function-reference for the full list of editors and converters.

Conditional statements

Use where to apply transformations conditionally:

span.attributes["db.statement"] = "REDACTED" where resource.attributes["service.name"] == "accounting"

Nil checks

Use nil for absence checking (not null):

resource.attributes["service.name"] != nil

Validation workflow

Validate config syntax — run otelcol validate --config=config.yaml to catch compilation errors before starting the Collector.
Test with the debug exporter — route transformed telemetry to a debug exporter and inspect the output:

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [transform]
      exporters: [debug]   # swap in production exporter once validated

Set error_mode: ignore in production — see Error handling.
Promote to production exporters — replace debug with the production exporter.

Common patterns

Set attributes
Drop telemetry by pattern
Drop stale data
Backfill missing timestamps
Filter processor example
Transform processor example
Defensive nil checks
Redact sensitive data — strategies: replace, mask, hash, delete, and drop.
Normalize high-cardinality attributes — path segments, IP masking, and attribute count/length limits.
Enrich telemetry with static attributes

Error handling

Compilation errors

Occur during processor initialization and prevent Collector startup:

Invalid syntax (missing quotes)
Unknown functions
Invalid path expressions
Type mismatches

Runtime errors

Occur during telemetry processing:

Accessing non-existent attributes
Type conversion failures
Function execution errors

Error mode configuration

Set error_mode explicitly for clarity; ignore is the default.

Mode	Behavior	When to use
`ignore` (default)	Logs the error and continues to the next statement	Production and general use — the default for the transform and filter processors
`propagate`	Returns the error up the pipeline, dropping the payload from the Collector	Development and strict environments where you want to catch every error
`silent`	Ignores errors without logging	High-volume pipelines with known-safe transforms where error logs are noise

processors:
  transform:
    error_mode: ignore
    trace_statements:
      - set(span.attributes["parsed"], ParseJSON(span.attributes["json_body"]))

Statements are a flat list; the Collector infers the context (span, metric, datapoint, log, and so on) from the path prefixes. Use the object form with an explicit context: only when a statement group mixes paths that cannot be inferred to a single context, or when you need a group-level condition or error_mode.

Performance

Use where clauses to skip items early.

# BAD — runs replace_pattern on every span
replace_pattern(span.attributes["url.path"], "/\\d+", "/{id}")

# GOOD — skips spans that lack the attribute
replace_pattern(span.attributes["url.path"], "/\\d+", "/{id}") where span.attributes["url.path"] != nil