OpenTelemetry Collector Processors

Processors sit between receivers and exporters in the Collector pipeline. They transform, filter, enrich, or batch telemetry data before it is exported. You can chain multiple processors together in a single pipeline. The following processors are the most relevant when sending data to Honeycomb. For the full list of available processors, visit the OpenTelemetry Collector processor documentation in the OpenTelemetry GitHub repository.

Batch processor

The batch processor groups telemetry into batches before sending to Honeycomb, which reduces the number of outbound connections and improves export efficiency. Include it in every pipeline as a baseline. The batch processor is included in the Core, Contrib, and Kubernetes distributions of the Collector.

How the batch processor works

The batch processor accumulates telemetry items and sends them together as a single request. It releases a batch when either the batch size reaches a configured limit or a timeout expires, whichever comes first. This reduces network overhead and helps stay within Honeycomb’s request size limits. By default, the batch processor uses a 200ms timeout and no size limit. For most pipelines, the defaults are a reasonable starting point.

Supported signals

The batch processor supports all three signal types and can be used in trace, metrics, and log pipelines without additional configuration.

Basic configuration

Add the batch processor to your Collector configuration file and include it in the relevant pipeline:

processors:
  batch:
...
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_http]

Place the batch processor last in your pipeline. Processors that drop or transform data, such as the filter processor, should run before batching so you aren’t batching data that will be dropped.

Use cases

The batch processor applies to several different scenarios:

Improve export efficiency: Reduce the number of outbound connections and network overhead by grouping telemetry into batches before sending to Honeycomb.
Handle large requests: Tune batch size to stay within Honeycomb’s 15MB request size limit. For configuration options, visit Run the Collector.

Filter processor

The filter processor drops telemetry that matches conditions you define before it reaches Honeycomb. It is one of the most versatile processors in the Collector, useful for reducing data volume, removing noisy signals, and preventing sensitive data from leaving your environment. The filter processor is included in the Core, Contrib, and Kubernetes distributions of the Collector.

How the filter processor works

The filter processor evaluates each telemetry item against the conditions you define. If any condition matches, the item is dropped. When multiple conditions are present, they are evaluated as an OR; the item is dropped if any single condition is true. Conditions are written in OTTL (OpenTelemetry Transformation Language), a scripting language used by several Collector processors to match and transform telemetry data.

Honeycomb translates all fields with the instrumentation_scope.name field into library.name. To filter based on instrumentation scope, use instrumentation_scope.name rather than library.name.

Supported signals

The filter processor supports traces, metrics, and logs. Use the appropriate configuration option for each:

Configuration option	Signal type
`traces.span`	Spans
`traces.spanevent`	Span events
`metrics.metric`	Metrics
`metrics.datapoint`	Data points
`logs.log_record`	Logs

Basic configuration

Add the filter processor to your Collector configuration file and include it in the relevant pipeline:

processors:
  filter:
    error_mode: ignore
    traces:
      span:
        - 'attributes["container.name"] == "app_container_1"'
...
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [filter, batch]
      exporters: [otlp_http]

The error_mode: ignore setting prevents the Collector from stopping when a condition cannot be evaluated.

Use cases

The filter processor applies to several different scenarios:

Reduce data volume: Drop noisy or unneeded telemetry from high-volume instrumentation libraries before they reach Honeycomb. For examples, visit Manage Data Volume: Filter Processor.
Filter sensitive data: Drop telemetry containing PII or other sensitive values before they leave your environment. To learn more, visit Handle Sensitive Information.

Attributes processor

The attributes processor adds, modifies, deletes, or hashes attributes on individual spans, metrics, or logs. It is one of the most broadly useful processors in the Collector, applicable to data quality, enrichment, compliance, and cost management scenarios. The attributes processor is included in the Contrib distribution of the Collector.

How the attributes processor works

The attributes processor applies a list of actions to attributes in order. Each action specifies a key, an action type, and optionally a value or source attribute. Available actions are:

insert: Adds a new attribute if the key doesn’t already exist.
update: Updates an existing attribute.
upsert: Inserts or updates regardless of whether the key exists.
delete: Removes the attribute.
hash: Replaces the value with a SHA1 hash of the original value.
extract: Extracts values from an existing attribute using a regex pattern.

Supported signals

The attributes processor supports traces, metrics, and logs.

Basic configuration

Add the attributes processor to your Collector configuration file and include it in the relevant pipeline:

processors:
  attributes:
    actions:
      - key: environment
        value: production
        action: insert
      - key: http.url
        action: delete
...
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [attributes, batch]
      exporters: [otlp_http]

Use cases

The attributes processor is most useful when you need fine-grained control over individual span, metric, or log attributes before they reach Honeycomb:

Enrich telemetry: Add deployment or environment metadata to spans, metrics, or logs before they reach Honeycomb.
Redact or remove sensitive data: Delete or hash attributes containing PII or other sensitive values before they leave your environment. To learn more, visit Handle Sensitive Information.
Reduce data volume: Remove unneeded attributes to reduce the size of your telemetry before it reaches Honeycomb.

Redaction processor

The redaction processor masks or removes span attribute values that match patterns you define, and can restrict which attributes are allowed to pass through the pipeline at all. It is designed specifically for compliance and security use cases where sensitive data must not reach any backend. The redaction processor is included in the Contrib distribution of the Collector.

How the redaction processor works

The processor operates in two modes:

allow_all_keys: false: Removes any attribute not on an explicit allowlist before checking values.
allow_all_keys: true: Keeps all attributes but masks values matching blocked patterns using regex.

Span attributes not on the allowed list are removed before value checks are applied.

Supported signals

The redaction processor supports traces only. For metrics or logs, use the attributes or transform processor instead.

Basic configuration

The following configuration masks values matching common sensitive patterns while allowing all other attributes to pass through:

processors:
  redaction:
    allow_all_keys: true
    blocked_values:
      - "^4[0-9]{12}(?:[0-9]{3})?$"          ## Visa
      - "^3[47][0-9]{13}$"                    ## Amex
      - "\b((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.|$)){4}\b" ## IP address
...
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [redaction, batch]
      exporters: [otlp_http]

Use cases

The redaction processor is purpose-built for compliance and security scenarios where sensitive values must not leave your environment:

Mask sensitive values: Block credit card numbers, IP addresses, and other sensitive patterns from reaching Honeycomb using regex-based blocklists.
Restrict allowed attributes: For allowlist-based configuration that controls which attributes are permitted through the pipeline at all, visit Handle Sensitive Information.

Transform processor

The transform processor modifies telemetry data using OTTL statements, enabling renaming attributes, setting span status, extracting values from existing attributes, and restructuring data before it reaches Honeycomb. It is the most powerful and flexible of the three attribute-manipulation processors. The transform processor is included in the Contrib distribution of the Collector.

How the transform processor works

The processor applies OTTL statements to telemetry in a specified context: resource, scope, span, metric, datapoint, or log. Statements are applied in order and can call OTTL functions to keep keys, replace patterns, set values, and more.

Supported signals

The transform processor supports traces, metrics, and logs.

Basic configuration

The following configuration masks a password that appears in a command line attribute:

processors:
  transform:
    trace_statements:
      - context: resource
        statements:
          - keep_keys(attributes, "service.name", "service.namespace", "cloud.region", "process.command_line")
          - replace_pattern(attributes["process.command_line"], "password\\=[^\\s]*(\\s?)", "password=***")
...
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [transform, batch]
      exporters: [otlp_http]

Use cases

The transform processor’s flexibility makes it applicable across several scenarios:

Mask sensitive data: Replace or redact sensitive values in attributes using pattern matching. To learn more, visit Handle Sensitive Information.
Restructure telemetry: Rename attributes, set span status, or extract values to conform to Honeycomb’s semantic conventions or your team’s naming standards.
Advanced transformations: The transform processor supports conditional logic, computed attributes, span status overrides, promoting resource attributes to span attributes, and mathematical operations using OTTL. For the full syntax and function reference, visit the OTTL documentation in OpenTelemetry’s GitHub repository.

Resource processor

The resource processor modifies resource attributes, which are the service-level metadata that applies to all telemetry from a service, such as service.name, service.version, and deployment.environment. Unlike the attributes processor, which modifies per-signal attributes on individual spans, metrics, or logs, the resource processor operates on the identity and context of the service generating the telemetry. The resource processor is included in the Contrib distribution of the Collector.

How the resource processor works

The resource processor applies actions to resource attributes using the same action model as the attributes processor: insert, update, upsert, delete, and hash. It supports environment variable substitution using ${VAR_NAME} syntax, which makes it useful for injecting deployment metadata at runtime.

Supported signals

The resource processor supports traces, metrics, and logs.

Basic configuration

Add the resource processor to your Collector configuration file to insert or update resource attributes, then include it in the relevant pipeline:

processors:
  resource:
    attributes:
      - key: deployment.environment
        value: production
        action: upsert
      - key: service.version
        value: ${GIT_COMMIT_SHA}
        action: upsert
...
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resource, batch]
      exporters: [otlp_http]

Use cases

The resource processor is most useful when you need to add or correct service-level metadata that applies uniformly across all telemetry:

Add deployment context: Attach environment, version, or region metadata to all telemetry from a service so you can filter and group by these attributes in Honeycomb.
Enrich infrastructure telemetry: Add or correct resource attributes on telemetry collected from infrastructure sources. To learn more, visit Enrich Infrastructure Telemetry.

Resource detection processor

The resource detection processor automatically detects resource attributes from the host environment and attaches them to telemetry. Rather than manually specifying metadata like host name, cloud region, or container details, the processor queries the environment directly and populates the attributes for you. The resource detection processor is included in the Contrib distribution of the Collector.

How the resource detection processor works

The processor uses a list of detectors you configure. Each detector queries a different source (environment variables, the host OS, or a cloud provider metadata API) and adds the attributes it finds to all telemetry passing through the pipeline. Use override: false to prevent the processor from overwriting attributes already set by your application. Available detectors include env, system, docker, gcp, ec2, ecs, eks, azure, and aks.

Supported signals

The resource detection processor supports traces, metrics, and logs.

Basic configuration

Configure the detectors that match your environment, then include the processor in the relevant pipeline:

processors:
  resourcedetection:
    detectors: [env, system, gcp, ec2, azure]
    timeout: 5s
    override: false
...
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resourcedetection, batch]
      exporters: [otlp_http]

Place the resource detection processor before the batch processor in your pipeline so resource attributes are attached before data is batched.

Use cases

The resource detection processor works best when you want infrastructure context attached automatically rather than configured manually:

Automatic infrastructure context: Attach cloud provider metadata, host name, and OS details to telemetry without manual configuration.
Enrich infrastructure telemetry: Combine with the resource processor to auto-detect infrastructure context and add deployment-specific metadata. To learn more, visit Enrich Infrastructure Telemetry.

Kubernetes attributes processor

The k8sattributes processor automatically attaches Kubernetes metadata (such as pod name, namespace, deployment name, and node name) to telemetry passing through the Collector. This makes it significantly easier to correlate application traces and metrics with the Kubernetes workloads that generated them in Honeycomb. The k8sattributes processor is included in the Contrib distribution of the Collector.

How the Kubernetes attributes processor works

The processor queries the Kubernetes API to build a table of pod metadata. As telemetry passes through the pipeline, it matches each item to a pod using the connection IP and attaches the pod’s metadata as resource attributes. The Collector’s service account must have RBAC permissions to read pod and replicaset resources from the Kubernetes API.

Supported signals

The k8sattributes processor supports traces, metrics, and logs.

Basic configuration

Configure the processor with the metadata fields you want to extract, then include it in the relevant pipeline:

processors:
  k8sattributes:
    auth_type: serviceAccount
    extract:
      metadata:
        - k8s.namespace.name
        - k8s.pod.name
        - k8s.pod.uid
        - k8s.deployment.name
        - k8s.node.name
...
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [k8sattributes, batch]
      exporters: [otlp_http]

The k8sattributes processor requires RBAC permissions to query the Kubernetes API. At minimum, the Collector’s service account needs get, watch, and list permissions on pods and replicasets resources.

Use cases

Honeycomb strongly recommends including the k8sattributes processor in any Collector that receives telemetry from Kubernetes pods:

Correlate application and infrastructure data: Attach pod and deployment metadata to application traces so you can group and filter by Kubernetes workload in Honeycomb.
Enrich infrastructure telemetry: Attach Kubernetes metadata to infrastructure telemetry so you can correlate pod metrics, cluster events, and logs with your application traces in Honeycomb. For full configuration guidance including RBAC setup, visit Enrich Infrastructure Telemetry.

Metrics transform processor

The metricstransform processor renames metrics, adds or updates metric labels, and applies regex-based transforms across multiple metric names simultaneously. It handles metric-specific transformations that go beyond what the attributes processor supports. The metricstransform processor is included in the Contrib distribution of the Collector.

How the metrics transform processor works

The processor applies a list of transforms, each targeting one or more metrics by name or regex pattern. Each transform can update the metric name, add or rename labels, and perform aggregate operations. Transforms are applied in order.

Supported signals

The metricstransform processor supports metrics only.

Basic configuration

Add the metricstransform processor to your Collector configuration file, then include it in the relevant pipeline:

processors:
  metricstransform:
    transforms:
      - include: system.cpu.usage
        action: update
        new_name: system.cpu.usage_time
      - include: ^.*$
        match_type: regexp
        action: update
        operations:
          - action: update_label
            label: cluster_name
            new_label: cluster-name
...
service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [metricstransform, batch]
      exporters: [otlp_http]

Use cases

The metricstransform processor is most useful when normalizing metric names and labels from different sources before they reach Honeycomb:

Normalize metric names: Standardize metric names from different sources before they reach Honeycomb, so queries and dashboards work consistently across services.
Rename labels: Update label names to match your team’s naming conventions or Honeycomb’s semantic conventions.
Adjust metrics granularity: Aggregate or downsample metrics before they reach Honeycomb to reduce data volume and control costs. To learn more about managing metrics volume and granularity in Honeycomb, visit Adjust Metrics Granularity.

Honeycomb-maintained processors

In addition to the standard OpenTelemetry Collector processors, Honeycomb maintains other processors available in the Honeycomb build of the Collector. These include three symbolication processors for resolving minified or obfuscated stack traces into human-readable symbols:

sourcemapprocessor: JavaScript and browser stack traces
dsymprocessor: iOS stack traces
proguardprocessor: Android stack traces

These processors are included by default in the Honeycomb build of the Collector. If you use another distribution or build your own, you can install them manually. To learn more, visit Symbolicate Stack Traces.

Sourcemap processor

The sourcemap processor resolves minified or obfuscated stack traces into human-readable symbols before telemetry reaches Honeycomb. It replaces minified names and addresses in JavaScript, iOS, Android, and React Native stack traces with symbols from provided source maps, giving you readable errors and stack traces in Honeycomb’s Errors UI. The sourcemap processor is a Honeycomb-maintained processor, not part of the standard OpenTelemetry Collector Contrib distribution. It is included by default in the Honeycomb OpenTelemetry Collector distribution.

How the sourcemap processor works

The processor reads stack trace attributes from incoming spans and resolves them against source map files you provide. Source maps can be stored on local disk, in Amazon S3, or in Google Cloud Storage. The processor supports language-based routing so it only runs on signals from JavaScript or TypeScript applications, avoiding unnecessary processing of telemetry from other languages.

Supported signals

The sourcemap processor supports traces only.

Basic configuration

Add the sourcemap processor to your Collector configuration file and include it in the relevant pipeline:

processors:
  source_map_symbolicator:
    source_map_store: file_store
    local_source_maps:
      path: /tmp/sourcemaps

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [source_map_symbolicator, batch]
      exporters: [otlp_http]

Use cases

The sourcemap processor is most useful for frontend and mobile applications where stack traces are minified or obfuscated before they reach Honeycomb:

Resolve JavaScript stack traces: Symbolicate minified browser JavaScript stack traces so errors are readable in Honeycomb’s Errors UI.
Resolve mobile stack traces: Symbolicate iOS (dSym) and Android (Proguard) stack traces from your mobile applications.

For full configuration guidance including S3 and GCS storage options, attribute mapping, and language-based routing, visit Symbolicate Stack Traces.

Filtering span events

To filter span events using the filterprocessor, use version 0.66.0 or higher of the OpenTelemetry Collector Contrib distribution: (Isn’t version v redundant?)

processors:
  filter:
    traces:
      spanevent:
        - 'attributes["grpc"] == true'
        - 'IsMatch(name, ".*grpc.*") == true'

To require multiple conditions to be true simultaneously, combine them in a single expression:

processors:
  filter:
    traces:
      spanevent:
        - 'attributes["grpc"] == true and IsMatch(name, ".*grpc.*") == true'

Honeycomb translates all fields with the instrumentation_scope.name field into library.name. To filter based on instrumentation scope, use instrumentation_scope.name rather than library.name.

Filtering across signals

The filter processor works across all OpenTelemetry signals, not only span events:

processors:
  filter:
    traces:
      span:
        - 'attributes["container.name"] == "app_container_1"'
        - 'resource.attributes["host.name"] == "localhost"'
        - 'name == "app_3"'
      spanevent:
        - 'attributes["grpc"] == true'
        - 'IsMatch(name, ".*grpc.*") == true'
    metrics:
      metric:
        - 'name == "my.metric" and attributes["my_label"] == "abc123"'
        - 'type == METRIC_DATA_TYPE_HISTOGRAM'
      datapoint:
        - 'metric.type == METRIC_DATA_TYPE_SUMMARY'
        - 'resource.attributes["service.name"] == "my_service_name"'
    logs:
      log_record:
        - 'IsMatch(body, ".*password.*") == true'
        - 'severity_number < SEVERITY_NUMBER_WARN'

Filtering Span Events and Other Data

Full Configuration File For Basic Usage

The final result of adding receivers, processors, exporters, and pipelines will look like this:

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  otlp_http:
    endpoint: "https://api.honeycomb.io:443" # US instance
    #endpoint: "https://api.eu1.honeycomb.io:443" # EU instance
    headers:
      "x-honeycomb-team": "YOUR_API_KEY"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_http]

If you are a Honeycomb Classic user, the Dataset also must be specified using the x-honeycomb-dataset header in the exporters section, in the line below the x-honeycomb-team. A Dataset is a bucket where data gets stored in Honeycomb.

exporters:
  otlp_http:
    endpoint: "https://api.honeycomb.io:443" # US instance
    #endpoint: "https://api.eu1.honeycomb.io:443" # EU instance
    headers:
      "x-honeycomb-team": "YOUR_API_KEY"
      "x-honeycomb-dataset": "YOUR_DATASET"

Metrics and Logs Signals

The Collector can handle OTLP metrics and logs signals in addition to traces. Metrics require a dataset in the exporter. Logs will use the service.name associated with the trace from which it originated, or a dataset if provided. It is possible to send these to the same or to multiple places in Honeycomb. To set a different pipeline with the same type of exporter, append the exporter with /my-pipeline. The following example exports OTLP application metrics to a specified dataset, and exports logs to the same place as traces.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  otlp_http:
    endpoint: "https://api.honeycomb.io:443" # US instance
    #endpoint: "https://api.eu1.honeycomb.io:443" # EU instance
    headers:
      "x-honeycomb-team": "YOUR_API_KEY"
  otlp_http/metrics:
    endpoint: "https://api.honeycomb.io:443" # US instance
    #endpoint: "https://api.eu1.honeycomb.io:443" # EU instance
    headers:
      "x-honeycomb-team": "YOUR_API_KEY"
      "x-honeycomb-dataset": "YOUR_METRICS_DATASET"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_http]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_http/metrics]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_http]

Symbolicate Web, iOS, Android, and React Native stack traces

Honeycomb provides several Collector processors for symbolicating stack traces from your browser, iOS, Android, and React Native applications. This gives you human-readable errors and stack traces in your frontend launchpad’s Errors UI.

For tutorials on setting up these processors, check out:

Documentation Index

​Batch processor

​How the batch processor works

​Supported signals

​Basic configuration

​Use cases

​Filter processor

​How the filter processor works

​Supported signals

​Basic configuration

​Use cases

​Attributes processor

​How the attributes processor works

​Supported signals

​Basic configuration

​Use cases

​Redaction processor

​How the redaction processor works

​Supported signals

​Basic configuration

​Use cases

​Transform processor

​How the transform processor works

​Supported signals

​Basic configuration

​Use cases

​Resource processor

​How the resource processor works

​Supported signals

​Basic configuration

​Use cases

​Resource detection processor

​How the resource detection processor works

​Supported signals

​Basic configuration

​Use cases

​Kubernetes attributes processor

​How the Kubernetes attributes processor works

​Supported signals

​Basic configuration

​Use cases

​Metrics transform processor

​How the metrics transform processor works

​Supported signals

​Basic configuration

​Use cases

​Honeycomb-maintained processors

​Sourcemap processor

​How the sourcemap processor works

​Supported signals

​Basic configuration

​Use cases

​Filtering span events

​Filtering across signals

​Filtering Span Events and Other Data

​Full Configuration File For Basic Usage

​Metrics and Logs Signals

​Symbolicate Web, iOS, Android, and React Native stack traces

Batch processor

How the batch processor works

Supported signals

Basic configuration

Use cases

Filter processor

How the filter processor works

Supported signals

Basic configuration

Use cases

Attributes processor

How the attributes processor works

Supported signals

Basic configuration

Use cases

Redaction processor

How the redaction processor works

Supported signals

Basic configuration

Use cases

Transform processor

How the transform processor works

Supported signals

Basic configuration

Use cases

Resource processor

How the resource processor works

Supported signals

Basic configuration

Use cases

Resource detection processor

How the resource detection processor works

Supported signals

Basic configuration

Use cases

Kubernetes attributes processor

How the Kubernetes attributes processor works

Supported signals

Basic configuration

Use cases

Metrics transform processor

How the metrics transform processor works

Supported signals

Basic configuration

Use cases

Honeycomb-maintained processors

Sourcemap processor

How the sourcemap processor works

Supported signals

Basic configuration

Use cases

Filtering span events

Filtering across signals

Filtering Span Events and Other Data

Full Configuration File For Basic Usage

Metrics and Logs Signals

Symbolicate Web, iOS, Android, and React Native stack traces