transform processor. Instead of filtering, we’ll apply transformations to telemetry signals — primarily traces — to set or modify attributes on resources, spans, and span events.
Start by replacing or commenting out any previous filter processor configuration and enable the transform processor in your Collector configuration. A minimal OpenTelemetry Collector snippet to enable the processor looks like this:
Transform processor basics
Thetransform processor executes OTTL statements to modify signals. It supports an error_mode option that controls behavior when a statement errors.
Setting
error_mode: ignore prevents a single statement failure from stopping processing of the signal. This is useful for experimentation or when applying many optional transformations.- Traces:
trace_statements - Metrics:
metric_statements - Logs:
log_statements
transform processor looks like this:
Contexts available in OTTL
OTTL exposes contexts that map to parts of a telemetry signal. Use the appropriate context for what you want to modify.| Context | Targets | Typical use |
|---|---|---|
resource | Resource attributes | Add service-level metadata (e.g., environment, platform) |
span | Span attributes and core span properties (name, kind, status) | Modify span-level metadata |
spanevent | Span events | Add or modify attributes on span events |
metric | Metric resource-level metric fields | Transform metric metadata |
datapoint | Individual metric datapoints | Modify values or labels |
log | Log records | Enrich or alter log attributes |
resource, span, or spanevent as needed.
Example: Set a resource attribute
Add aplatform resource attribute to all traces using the resource context.
debug exporter, you should see platform: Str(kubernetes) in resource attributes for incoming traces (trimmed):
In production, avoid applying broad resource or span changes to all signals. Scope transformations to only the resources or spans that need modification to reduce risk of unintended side effects.
Example: Add an attribute to a span
To set an attribute on spans, use thespan context:
Span events: add attributes to events
Ensure your instrumentation emits span events. Example Python snippet that sets span attributes and adds an event:Conditional statements: restrict statements to specific spans
Avoid modifying every span by usingwhere clauses to apply statements conditionally.
Example: add an attribute only to spans with name == "process payment".
Use the conditions block to avoid repeating where
When multiple statements share the same condition, group them under conditions for readability and maintainability.
statements under a context with conditions are executed only when the condition(s) evaluate to true.
Best practices and summary
- Use the
transformprocessor to modify resource, span, and span event data where necessary. - Choose the appropriate context (
resource,span,spanevent) for targeted changes. - Prefer scoped transformations using
whereorconditionsrather than global modifications. - Use
error_modeto control how statement errors are handled while testing or in production. - Test with a
debugexporter to verify expected output before deploying changes.
set operations and scoping with contexts and conditions. OTTL supports more advanced expressions and transformations for complex use cases.
Links and references
- OpenTelemetry Collector Documentation
- OTTL specification and examples
- OpenTelemetry Python instrumentation