otel-ottl（奥特尔酒店）

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

Connectors

Receivers

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

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

Replace known sensitive attributes with a fixed placeholder. Always guard with a nil check to avoid creating the attribute when it does not exist.

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

Redact authorization and session headers

processors:
  transform/redact-headers:
    error_mode: ignore
    trace_statements:
      - context: span
        statements:
          - set(span.attributes["http.request.header.authorization"], "REDACTED") where span.attributes["http.request.header.authorization"] != nil
          - set(span.attributes["http.request.header.cookie"], "REDACTED") where span.attributes["http.request.header.cookie"] != nil
          - set(span.attributes["http.response.header.set-cookie"], "REDACTED") where span.attributes["http.response.header.set-cookie"] != nil
    log_statements:
      - context: log
        statements:
          - set(log.attributes["http.request.header.authorization"], "REDACTED") where log.attributes["http.request.header.authorization"] != nil
          - set(log.attributes["http.request.header.cookie"], "REDACTED") where log.attributes["http.request.header.cookie"] != nil

Mask credit card numbers in log bodies

Use replace_pattern to replace patterns matching sensitive data while preserving the rest of the field. For example, the following pattern matches 13–19 digit sequences (covering Visa, Mastercard, Amex, and others) and replaces them with a masked value.

processors:
  transform/redact-credit-cards:
    error_mode: ignore
    log_statements:
      - context: log
        statements:
          - replace_pattern(log.body["string"], "\\b(\\d{4})\\d{5,11}(\\d{4})\\b", "$$1****$$2")

Replace email addresses with a hash

Use a hash function to replace email addresses with a non-reversible identifier that still allows correlation across records.

processors:
  transform/hash-emails:
    error_mode: ignore
    trace_statements:
      - context: span
        statements:
          - set(span.attributes["user.email"], SHA256(span.attributes["user.email"])) where span.attributes["user.email"] != nil
    log_statements:
      - context: log
        statements:
          - set(log.attributes["user.email"], SHA256(log.attributes["user.email"])) where log.attributes["user.email"] != nil

Delete attributes that should never be exported

Use delete_key to remove attributes entirely rather than replacing them with a placeholder.

processors:
  transform/delete-sensitive:
    error_mode: ignore
    trace_statements:
      - context: span
        statements:
          - delete_key(span.attributes, "credit-card.number") where IsMatch(span.attributes["credit-card.number"], "(?i)(password|secret|token)")
    log_statements:
      - context: log
        statements:
          - delete_key(log.attributes, "request.body")

Drop log records containing sensitive data

Use the filter processor to drop entire log records that match a sensitive pattern, when redaction is not sufficient.

processors:
  filter/drop-sensitive-logs:
    error_mode: ignore
    logs:
      log_record:
        - 'IsMatch(log.body["string"], "(?i)-----BEGIN (RSA |EC )?PRIVATE KEY-----")'

Pipeline placement

Place redaction processors after enrichment processors (resourcedetection, k8sattributes, resource) and before exporters. Redaction must run after all attributes have been set, but before telemetry leaves the Collector. See processor ordering for the full ordering guidance.

Application-level sanitization is the first line of defence. Use Collector-side redaction as a safety net, not a substitute for source-level prevention. See the sensitive data rule in the otel-instrumentation skill for application-level guidance.

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.*$")

Normalize high-cardinality attributes

High-cardinality attributes — URL paths with embedded IDs, long freeform strings, or unbounded attribute maps — inflate storage costs and degrade query performance. Use OTTL in a transform processor to normalize these attributes before export.

Replace dynamic path segments

Replace numeric IDs and UUIDs in url.path and http.route with fixed placeholders to collapse cardinality.

processors:
  transform/normalize-paths:
    error_mode: ignore
    trace_statements:
      - context: span
        statements:
          - replace_pattern(span.attributes["url.path"], "/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", "/{uuid}") where span.attributes["url.path"] != nil
          - replace_pattern(span.attributes["url.path"], "/\\d+", "/{id}") where span.attributes["url.path"] != nil
          - replace_pattern(span.attributes["http.route"], "/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", "/{uuid}") where span.attributes["http.route"] != nil
          - replace_pattern(span.attributes["http.route"], "/\\d+", "/{id}") where span.attributes["http.route"] != nil

Mask IP addresses to subnet

Replace the last octet of IPv4 addresses with 0 to reduce cardinality while preserving subnet-level information.

processors:
  transform/mask-ips:
    error_mode: ignore
    trace_statements:
      - context: span
        statements:
          - replace_pattern(span.attributes["client.address"], "(\\d{1,3}\\.\\d{1,3}\\.\\d{1,3})\\.\\d{1,3}", "$$1.0") where span.attributes["client.address"] != nil
    log_statements:
      - context: log
        statements:
          - replace_pattern(log.attributes["client.address"], "(\\d{1,3}\\.\\d{1,3}\\.\\d{1,3})\\.\\d{1,3}", "$$1.0") where log.attributes["client.address"] != nil

Limit attribute count and value length

Use limit and truncate_all to enforce bounds on attribute maps that may grow unboundedly.

processors:
  transform/limit-attributes:
    error_mode: ignore
    trace_statements:
      - context: span
        statements:
          - limit(span.attributes, 64, [])
          - truncate_all(span.attributes, 256)
    log_statements:
      - context: log
        statements:
          - limit(log.attributes, 64, [])
          - truncate_all(log.attributes, 256)

Enrich telemetry with static attributes

When resourcedetection or k8sattributes processors are not available — for example, in non-Kubernetes deployments or when the Collector runs outside the cluster — set resource attributes explicitly.

processors:
  resource/static-env:
    attributes:
      - key: deployment.environment.name
        value: production
        action: upsert
      - key: k8s.cluster.name
        value: prod-us-west-2
        action: upsert

Use the resource processor (not the transform processor) for static resource attributes. The resource processor operates at the resource level directly, while transform requires a resource context and explicit path expressions.

To copy a resource attribute down to the span or log level — for example, when the backend does not propagate resource context — use the transform processor:

processors:
  transform/copy-resource:
    error_mode: ignore
    trace_statements:
      - context: span
        statements:
          - set(span.attributes["deployment.environment.name"], resource.attributes["deployment.environment.name"]) where resource.attributes["deployment.environment.name"] != nil

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.

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.

Converters: type checking

Converters: type conversion

Converters: string manipulation

Converters: Hashing

Converters: encoding and decoding

Converters: Parsing

Converters: Time and Date

Converters: Collections

Converters: IDs and Encoding

Converters: XML

Converters: Miscellaneous

References

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