OpenTelemetry Transformation Language (OTTL)

Use OTTL to transform, filter, and manipulate telemetry data inside the OpenTelemetry Collector — without changing application code.

Components that use OTTL

OTTL is not limited to the transform and filter processors. The following Collector components accept OTTL expressions in their configuration.

Processors

Component	Use case
transform	Modify, enrich, or redact telemetry (set attributes, rename fields, truncate values)
filter	Drop telemetry entirely (discard metrics by name, drop spans by status, remove noisy logs)
attributes	Insert, update, delete, or hash resource and record attributes
span	Rename spans and set span status based on attribute values
tailsampling	Sample traces based on OTTL conditions (e.g., keep error traces, drop health checks)
cumulativetodelta	Convert cumulative metrics to delta temporality with OTTL-based metric selection
logdedup	Deduplicate log records using OTTL conditions
lookup	Enrich telemetry by looking up values from external tables using OTTL expressions

Connectors

Component	Use case
routing	Route telemetry to different pipelines based on OTTL conditions
count	Count spans, metrics, or logs matching OTTL conditions and emit as metrics
sum	Sum numeric values from telemetry matching OTTL conditions and emit as metrics
signaltometrics	Generate metrics from spans or logs using OTTL expressions for attribute extraction

Receivers

Component	Use case
hostmetrics	Filter host metrics at collection time using OTTL conditions

OTTL syntax

Path expressions

Navigate telemetry data using dot notation:

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

Contexts (first path segment) map to OpenTelemetry signal structures:

• resource - Resource-level attributes
• scope - Instrumentation scope
• span - Span data (traces)
• spanevent - Span events
• metric - Metric metadata
• datapoint - Metric data points
• log - Log records

Enumerations

Several fields accept int64 values exposed as global constants:

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

Operators

Category	Operators
Assignment	=
Comparison	==, !=, >, <, >=, <=
Logical	and, or, not

Functions

Converters (uppercase, pure functions that 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, functions with side-effects that modify data):

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

Conditional statements

The where clause applies transformations conditionally:

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

Nil checks

OTTL uses nil for absence checking (not null):

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

Common patterns

Set attributes

set(resource.attributes["k8s.cluster.name"], "prod-aws-us-west-2")

Redact sensitive data

set(span.attributes["http.request.header.authorization"], "REDACTED") where span.attributes["http.request.header.authorization"] != nil

Drop telemetry by pattern

In a filter processor, matching expressions cause data to be dropped:

IsMatch(metric.name, "^k8s\\.replicaset\\..*$")

Drop stale data

time_unix_nano < UnixNano(Now()) - 21600000000000

Backfill missing timestamps

processors:
  transform:
    log_statements:
      - context: log
        statements:
          - set(log.observed_time, Now()) where log.observed_time_unix_nano == 0
          - set(log.time, log.observed_time) where log.time_unix_nano == 0

Filter processor example

processors:
  filter:
    metrics:
      datapoint:
        - 'IsMatch(ConvertCase(String(metric.name), "lower"), "^k8s\\.replicaset\\.")'

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [filter, batch]
      exporters: [debug]

Transform processor example

processors:
  transform:
    trace_statements:
      - context: span
        statements:
          - set(span.status.code, STATUS_CODE_ERROR) where span.attributes["http.response.status_code"] >= 500
          - set(span.attributes["env"], "production") where resource.attributes["deployment.environment"] == "prod"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [transform, batch]
      exporters: [debug]

Defensive nil checks

Always check for nil before operating on optional attributes:

resource.attributes["service.namespace"] != nil
and
IsMatch(ConvertCase(String(resource.attributes["service.namespace"]), "lower"), "^platform.*$")

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

Always set error_mode explicitly. The default (propagate) stops processing the current item on any error, which can silently drop telemetry in production.

Mode	Behavior	When to use
propagate (default)	Stops processing current item	Development and strict environments where you want to catch every error
ignore	Logs error, continues processing	Production — set this unless you have a specific reason not to
silent	Ignores errors without logging	High-volume pipelines with known-safe transforms where error logs are noise

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

Performance

OTTL statements compile once at startup and execute as optimized function chains at runtime. There is no need to optimize for compilation speed — focus on reducing the number of statements that evaluate per telemetry item. Use where clauses to skip items early rather than applying unconditional transforms.

Function reference

Editors

Editors modify telemetry data in-place. They are lowercase.

Function	Signature	Description
append	append(target, Optional[value], Optional[values])	Appends single or multiple values to a target field, converting scalars to arrays if needed
delete_key	delete_key(target, key)	Removes a key from a map
delete_matching_keys	delete_matching_keys(target, pattern)	Removes all keys matching a regex pattern
flatten	flatten(target, Optional[prefix], Optional[depth])	Flattens nested maps to the root level
keep_keys	keep_keys(target, keys[])	Removes all keys NOT in the supplied list
keep_matching_keys	keep_matching_keys(target, pattern)	Keeps only keys matching a regex pattern
limit	limit(target, limit, priority_keys[])	Reduces map size to not exceed limit, preserving priority keys
merge_maps	merge_maps(target, source, strategy)	Merges source into target (strategy: insert, update, upsert)
replace_all_matches	replace_all_matches(target, pattern, replacement)	Replaces matching string values using glob patterns
replace_all_patterns	replace_all_patterns(target, mode, regex, replacement)	Replaces segments matching regex (mode: key or value)
replace_match	replace_match(target, pattern, replacement)	Replaces entire string if it matches a glob pattern
replace_pattern	replace_pattern(target, regex, replacement)	Replaces string sections matching a regex
set	set(target, value)	Sets a telemetry field to a value
truncate_all	truncate_all(target, limit)	Truncates all string values in a map to a max length

Converters: type checking

Function	Signature	Description
IsBool	IsBool(value)	Returns true if value is boolean
IsDouble	IsDouble(value)	Returns true if value is float64
IsInt	IsInt(value)	Returns true if value is int64
IsMap	IsMap(value)	Returns true if value is a map
IsList	IsList(value)	Returns true if value is a list
IsMatch	IsMatch(target, pattern)	Returns true if target matches regex pattern
IsRootSpan	IsRootSpan()	Returns true if span has no parent
IsString	IsString(value)	Returns true if value is a string

Converters: type conversion

Function	Signature	Description
Bool	Bool(value)	Converts value to boolean
Double	Double(value)	Converts value to float64
Int	Int(value)	Converts value to int64
String	String(value)	Converts value to string

Converters: string manipulation

Function	Signature	Description
Concat	Concat(values[], delimiter)	Concatenates values with a delimiter
ConvertCase	ConvertCase(target, toCase)	Converts to lower, upper, snake, or camel
HasPrefix	HasPrefix(value, prefix)	Returns true if value starts with prefix
HasSuffix	HasSuffix(value, suffix)	Returns true if value ends with suffix
Index	Index(target, value)	Returns first index of value in target, or -1
Split	Split(target, delimiter)	Splits string into array by delimiter
Substring	Substring(target, start, length)	Extracts substring from start position
ToCamelCase	ToCamelCase(target)	Converts to CamelCase
ToLowerCase	ToLowerCase(target)	Converts to lowercase
ToSnakeCase	ToSnakeCase(target)	Converts to snake_case
ToUpperCase	ToUpperCase(target)	Converts to UPPERCASE
Trim	Trim(target, Optional[char])	Removes leading/trailing characters
TrimPrefix	TrimPrefix(value, prefix)	Removes leading prefix
TrimSuffix	TrimSuffix(value, suffix)	Removes trailing suffix

Converters: Hashing

Function	Signature	Description
FNV	FNV(value)	Returns FNV hash as int64
MD5	MD5(value)	Returns MD5 hash as hex string
Murmur3Hash	Murmur3Hash(target)	Returns 32-bit Murmur3 hash as hex string
Murmur3Hash128	Murmur3Hash128(target)	Returns 128-bit Murmur3 hash as hex string
SHA1	SHA1(value)	Returns SHA1 hash as hex string
SHA256	SHA256(value)	Returns SHA256 hash as hex string
SHA512	SHA512(value)	Returns SHA512 hash as hex string

Converters: encoding and decoding

Function	Signature	Description
Decode	Decode(value, encoding)	Decodes string (base64, base64-raw, base64-url, IANA encodings)
Hex	Hex(value)	Returns hexadecimal representation

Converters: Parsing

Function	Signature	Description
ExtractPatterns	ExtractPatterns(target, pattern)	Extracts named regex capture groups into a map
ExtractGrokPatterns	ExtractGrokPatterns(target, pattern, Optional[namedOnly], Optional[defs])	Parses unstructured data using grok patterns
ParseCSV	ParseCSV(target, headers, Optional[delimiter], Optional[headerDelimiter], Optional[mode])	Parses CSV string to map
ParseInt	ParseInt(target, base)	Parses string as integer in given base (2-36)
ParseJSON	ParseJSON(target)	Parses JSON string to map or slice
ParseKeyValue	ParseKeyValue(target, Optional[delimiter], Optional[pair_delimiter])	Parses key-value string to map
ParseSeverity	ParseSeverity(target, severityMapping)	Maps log level value to severity string
ParseSimplifiedXML	ParseSimplifiedXML(target)	Parses XML string to map (ignores attributes)
ParseXML	ParseXML(target)	Parses XML string to map (preserves structure)

Converters: Time and Date

Function	Signature	Description
Day	Day(value)	Returns day component from time
Duration	Duration(duration)	Parses duration string (e.g. "3s", "333ms")
FormatTime	FormatTime(time, format)	Formats time to string using Go layout
Hour	Hour(value)	Returns hour component from time
Hours	Hours(value)	Returns duration as floating-point hours
Minute	Minute(value)	Returns minute component from time
Minutes	Minutes(value)	Returns duration as floating-point minutes
Month	Month(value)	Returns month component from time
Nanosecond	Nanosecond(value)	Returns nanosecond component from time
Nanoseconds	Nanoseconds(value)	Returns duration as nanosecond count
Now	Now()	Returns current time
Second	Second(value)	Returns second component from time
Seconds	Seconds(value)	Returns duration as floating-point seconds
Time	Time(target, format, Optional[location], Optional[locale])	Parses string to time
TruncateTime	TruncateTime(time, duration)	Truncates time to multiple of duration
Unix	Unix(seconds, Optional[nanoseconds])	Creates time from Unix epoch
UnixMicro	UnixMicro(value)	Returns time as microseconds since epoch
UnixMilli	UnixMilli(value)	Returns time as milliseconds since epoch
UnixNano	UnixNano(value)	Returns time as nanoseconds since epoch
UnixSeconds	UnixSeconds(value)	Returns time as seconds since epoch
Weekday	Weekday(value)	Returns day of week from time
Year	Year(value)	Returns year component from time

Converters: Collections

Function	Signature	Description
ContainsValue	ContainsValue(target, item)	Returns true if item exists in slice
Format	Format(formatString, args[])	Formats string using fmt.Sprintf syntax
Keys	Keys(target)	Returns all keys from a map
Len	Len(target)	Returns length of string, slice, or map
SliceToMap	SliceToMap(target, Optional[keyPath], Optional[valuePath])	Converts slice of objects to map
Sort	Sort(target, Optional[order])	Sorts array (asc or desc)
ToKeyValueString	ToKeyValueString(target, Optional[delim], Optional[pairDelim], Optional[sort])	Converts map to key-value string
Values	Values(target)	Returns all values from a map

Converters: IDs and Encoding

Function	Signature	Description
ProfileID	ProfileID(bytes|string)	Creates ProfileID from 16 bytes or 32 hex chars
SpanID	SpanID(bytes|string)	Creates SpanID from 8 bytes or 16 hex chars
TraceID	TraceID(bytes|string)	Creates TraceID from 16 bytes or 32 hex chars
UUID	UUID()	Generates a new UUID
UUIDv7	UUIDv7()	Generates a new UUIDv7

Converters: XML

Function	Signature	Description
ConvertAttributesToElementsXML	ConvertAttributesToElementsXML(target, Optional[xpath])	Converts XML attributes to child elements
ConvertTextToElementsXML	ConvertTextToElementsXML(target, Optional[xpath], Optional[name])	Wraps XML text content in elements
GetXML	GetXML(target, xpath)	Returns XML elements matching XPath
InsertXML	InsertXML(target, xpath, value)	Inserts XML at XPath locations
RemoveXML	RemoveXML(target, xpath)	Removes XML elements matching XPath

Converters: Miscellaneous

Function	Signature	Description
CommunityID	CommunityID(srcIP, srcPort, dstIP, dstPort, Optional[proto], Optional[seed])	Generates network flow hash
IsValidLuhn	IsValidLuhn(value)	Returns true if value passes Luhn check
Log	Log(value)	Returns natural logarithm as float64
URL	URL(url_string)	Parses URL into components (scheme, host, path, etc.)
UserAgent	UserAgent(value)	Parses user-agent string into map (name, version, OS)

References

• OTTL Guide
• OTTL Specification
• OTTL Functions Reference
• OTTL Playground