Attributes Processor

Available in: core, contrib, k8s Maintainers: @boostchicken Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

The attributes processor modifies attributes of a span, log, or metric. Please refer to config.go for the config spec. This processor also supports the ability to filter and match input data to determine if they should be included or excluded for specified actions. It takes a list of actions which are performed in order specified in the config. The supported actions are:

insert: Inserts a new attribute in input data where the key does not already exist.
update: Updates an attribute in input data where the key does exist.
upsert: Performs insert or update. Inserts a new attribute in input data where the key does not already exist and updates an attribute in input data where the key does exist.
delete: Deletes an attribute from the input data.
hash: Hashes (SHA1) an existing attribute value.
extract: Extracts values using a regular expression rule from the input key to target keys specified in the rule. If a target key already exists, it will be overridden. Note: It behaves similar to the Span Processor to_attributes setting with the existing attribute as the source.
convert: Converts an existing attribute to a specified type.

For the actions insert, update and upsert,

key is required
one of value, from_attribute, from_context, or default_value is required
action is required.

  # Key specifies the attribute to act upon.
- key: <key>
  action: {insert, update, upsert}
  # Value specifies the value to populate for the key.
  # The type is inferred from the configuration.
  value: <value>

  # Key specifies the attribute to act upon.
- key: <key>
  action: {insert, update, upsert}
  # FromAttribute specifies the attribute from the input data to use to populate
  # the value. If the attribute doesn't exist, no action is performed.
  from_attribute: <other key>

  # Key specifies the attribute to act upon.
- key: <key>
  action: {insert, update, upsert}
  # FromContext specifies the context value to use to populate the attribute value. 
  # If the key is prefixed with `metadata.`, the values are searched
  # in the receiver's transport protocol additional information like gRPC Metadata or HTTP Headers
  # (be sure to set `include_metadata: true` on the receiver).
  # If the key is prefixed with `auth.`, the values are searched
  # in the authentication information set by the server authenticator.
  # Refer to the server authenticator's documentation part of your pipeline for more information about which attributes are available.
  # If the key is `client.address`, the value will be set to the client address. 
  # If the key doesn't exist, no action is performed.
  # If the key has multiple values the values will be joined with `;` separator.
  from_context: <other key>

  # Key specifies the attribute to act upon.
- key: <key>
  action: {insert, update, upsert}
  # DefaultValue specifies the value to use if value/from_attribute/from_context
  # doesn't provide a value (e.g., environment variable not set, attribute doesn't exist).
  # Only used with INSERT, UPDATE, and UPSERT actions.
  default_value: <value>

For the delete action,

key and/or pattern is required
action: delete is required.

- key: <key>
  action: delete
  # Rule specifies the regex pattern for attribute names to act upon.
  pattern: <regular pattern>

For the hash action,

key and/or pattern is required
action: hash is required.

# Key specifies the attribute to act upon.
- key: <key>
  action: hash
  # Rule specifies the regex pattern for attribute names to act upon.
  pattern: <regular pattern>

For the extract action,

key is required
pattern is required.

# Key specifies the attribute to extract values from.
# The value of `key` is NOT altered.
- key: <key>
 # Rule specifies the regex pattern used to extract attributes from the value
 # of `key`.
 # The submatchers must be named.
 # If attributes already exist, they will be overwritten.
 pattern: <regular pattern with named matchers>
 action: extract

For the convert action,

key is required
action: convert is required.
converted_type is required and must be one of int, double or string

# Key specifies the attribute to act upon.
- key: <key>
  action: convert
  converted_type: <int|double|string>

Default Values

The default_value field can be used to specify a fallback value when the primary value source (e.g., attribute, or context value) is not available. This is useful for:

Providing sensible defaults when attributes don’t exist
Ensuring the pipeline doesn’t fail due to missing configuration

The list of actions can be composed to create rich scenarios, such as back filling attribute, copying values to a new key, redacting sensitive information. The following is a sample configuration.

processors:
  attributes/example:
    actions:
      - key: db.table
        action: delete
      - key: redacted_span
        value: true
        action: upsert
      - key: copy_key
        from_attribute: key_original
        action: update
      - key: account_id
        value: 2245
        action: insert
      - key: account_password
        action: delete
      - key: account_email
        action: hash
      - key: http.status_code
        action: convert
        converted_type: int
      # Use default_value when source attribute doesn't exist
      - key: region
        from_attribute: cloud.region
        default_value: "us-east-1"
        action: insert
      # Use default_value when context value is not available
      - key: tenant_id
        from_context: "metadata.tenant"
        default_value: "default-tenant"
        action: upsert

Refer to config.yaml for detailed examples on using the processor.

Attributes Processor for Metrics vs. Metric Transform Processor

Regarding metric support, these two processors have overlapping functionality. They can both do simple modifications of metric attribute key-value pairs. As a general rule the attributes processor has more attribute related functionality, while the metrics transform processor can do much more data manipulation. The attributes processor is preferred when the only needed functionality is overlapping, as it natively uses the official OpenTelemetry data model. However, if the metric transform processor is already in use or its extra functionality is necessary, there’s no need to migrate away from it. Shared functionality

Add attributes
Update values of attributes

Attribute processor specific functionality

delete
hash
extract

Metric transform processor specific functionality

Rename metrics
Delete data points
Toggle data type
Scale value
Aggregate across label sets
Aggregate across label values

Include/Exclude Filtering

The attribute processor exposes an option to provide a set of properties of a span, log or metric record to match against to determine if the input data should be included or excluded from the processor. To configure this option, under include and/or exclude at least match_type and one of the following is required:

For spans, one of services, span_names, span_kinds, attributes, resources or libraries must be specified with a non-empty value for a valid configuration. The log_bodies, log_severity_texts, log_severity_number and metric_names fields are invalid.
For logs, one of log_bodies, log_severity_texts, log_severity_number, attributes, resources or libraries must be specified with a non-empty value for a valid configuration. The span_names, span_kinds, metric_names and services fields are invalid.
For metrics, one of metric_names or resources must be specified with a valid non-empty value for a valid configuration. The span_names, span_kinds, log_bodies, log_severity_texts, log_severity_number, services, attributes and libraries fields are invalid.

Note: If both include and exclude are specified, the include properties are checked before the exclude properties.

attributes:
    # include and/or exclude can be specified. However, the include properties
    # are always checked before the exclude properties.
    {include, exclude}:
      # At least one of services, span_names or attributes must be specified.
      # It is supported to have more than one specified, but all of the specified
      # conditions must evaluate to true for a match to occur.

      # match_type controls how items in "services", "span_names", and "attributes"
      # arrays are interpreted. Possible values are "regexp" or "strict".
      # This is a required field.
      match_type: {strict, regexp}

      # regexp is an optional configuration section for match_type regexp.
      regexp:
        # < see "Match Configuration" below >

      # services specify an array of items to match the service name against.
      # A match occurs if the span service name matches at least one of the items.
      # This is an optional field.
      services: [<item1>, ..., <itemN>]

      # resources specifies a list of resources to match against.
      # A match occurs if the input data resources matches at least one of the items.
      # This is an optional field.
      resources:
          # Key specifies the resource to match against.
        - key: <key>
          # Value specifies the exact value to match against.
          # If not specified, a match occurs if the key is present in the resources.
          value: {value}

      # libraries specify a list of items to match the implementation library against.
      # A match occurs if the input data implementation library matches at least one of the items.
      # This is an optional field.
      libraries: [<item1>, ..., <itemN>]
          # Name specifies the library to match against.
        - name: <name>
          # Version specifies the exact version to match against.
          # This is an optional field.
          # If the field is not set, any version will match.
          # If the field is set to an empty string, only an
          # empty string version will match.
          version: {version}

      # The span name must match at least one of the items.
      # This is an optional field.
      span_names: [<item1>, ..., <itemN>]

      # The span kind must match at least one of the items.
      # This is an optional field.
      span_kinds: [<item1>, ..., <itemN>]

      # The log body must match at least one of the items.
      # Currently only string body types are supported.
      # This is an optional field.
      log_bodies: [<item1>, ..., <itemN>]

      # The log severity text must match at least one of the items.
      # This is an optional field.
      log_severity_texts: [<item1>, ..., <itemN>]

      # The log severity number defines how to match against a log record's
      # SeverityNumber, if defined.
      # This is an optional field.
      log_severity_number:
        # Min is the lowest severity that may be matched.
        # e.g. if this is plog.SeverityNumberInfo, 
        # INFO, WARN, ERROR, and FATAL logs will match.
        min: <int>
        # MatchUndefined controls whether logs with "undefined" severity matches.
        # If this is true, entries with undefined severity will match.
        match_undefined: <bool>

      # The metric name must match at least one of the items.
      # This is an optional field.
      metric_names: [<item1>, ..., <itemN>]

      # Attributes specifies the list of attributes to match against.
      # All of these attributes must match for a match to occur.
      # This is an optional field.
      attributes:
          # Key specifies the attribute to match against.
        - key: <key>
          # Value specifies the value to match against.
          # If not specified, a match occurs if the key is present in the attributes.
          value: {value}

Match Configuration

Some match_type values have additional configuration options that can be specified. The match_type value is the name of the configuration section. These sections are optional.

# regexp is an optional configuration section for match_type regexp.
regexp:
  # cacheenabled determines whether match results are LRU cached to make subsequent matches faster.
  # Cache size is unlimited unless cachemaxnumentries is also specified.
  cacheenabled: <bool>
  # cachemaxnumentries is the max number of entries of the LRU cache; ignored if cacheenabled is false.
  cachemaxnumentries: <int>

Warnings

In general, the Attributes processor is a very safe processor to use. Care only needs to be taken when modifying data point attributes:

Identity Conflict: Reducing/changing existing data point attributes has the potential to create an identity conflict since the Attributes processor does not perform any re-aggregation of the data points. Adding new attributes to data points is safe.

Configuration

Example Configuration

# The following example demonstrates inserting keys/values into spans.
attributes/insert:
  actions:
    # The following inserts a new attribute {"attribute1": 123} to spans where
    # the key "attribute1" doesn't exist.
    # The type of `attribute1` is inferred by the configuration.
    #  `123` is an integer and is stored as an integer in the attributes.
    # This demonstrates how to backfill spans with an attribute that may
    # not have been sent by all clients.
    - key: "attribute1"
      value: 123
      action: insert
    # The following uses the value from attribute "anotherkey" to insert a new
    # attribute {"string key": <value from attribute "anotherkey">} to spans
    # where the key "string key" does not exist. If the attribute "anotherkey"
    # doesn't exist, no new attribute is inserted to spans.
    - key: "string key"
      from_attribute: "anotherkey"
      action: insert

# The following example demonstrates using regex to create new attributes
# based on the value of another attribute.
attributes/regex_insert:
  actions:
    # The following uses the value from `key:http.url` to upsert attributes
    # to the target keys specified in the `rule`.
    # (Insert attributes for target keys that do not exist and update keys
    # that exist.)
    # Given http.url = http://example.com/path?queryParam1=value1,queryParam2=value2
    # then the following attributes will be inserted:
    # http_protocol: http
    # http_domain: example.com
    # http_path: path
    # http_query_params=queryParam1=value1,queryParam2=value2
    # http.url value does NOT change.
    # Note: Similar to the Span Processor, if a target key already exists,
    # it will be updated.
    - key: "http.url"
      pattern: ^(?P<http_protocol>.*):\/\/(?P<http_domain>.*)\/(?P<http_path>.*)(\?|\&)(?P<http_query_params>.*)
      action: extract

# The following demonstrates configuring the processor to only update existing
# keys in an attribute.
# Note: `action: update` must be set.
attributes/update:
  actions:
    # The following updates the attribute 'boo' using the value from attribute
    # 'foo'. Spans without the attribute 'boo' will not change.
    - key: "boo"
      from_attribute: "foo"
      action: update
    # The following updates the attribute to { "db.secret": "redacted"}.
    # This demonstrates sanitizing spans of sensitive data.
    - key: db.secret
      value: redacted
      action: update

# The following demonstrates setting an attribute on both spans where the
# key does exist and the key doesn't exist.
attributes/upsert:
  actions:
    # The following demonstrates how to set an attribute on all spans.
    # Any spans that already had `region` now have value `planet-earth`.
    # This can be done to set properties for all traces without
    # requiring an instrumentation change.
    - key: region
      value: "planet-earth"
      action: upsert

    # The following demonstrates copying a value to a new key.
    # Note: If a span doesn't contain `user_key`, no new attribute `new_user_key`
    # is created.
    - key: new_user_key
      from_attribute: user_key
      action: upsert

# The following demonstrates deleting keys from an attribute.
attributes/delete:
  actions:
    - key: credit_card
      action: delete
    - key: duplicate_key
      action: delete

# The following demonstrates hash existing attribute values.
attributes/hash:
  actions:
    - key: user.email
      action: hash

# The following demonstrates converting the type of existing attribute values.
attributes/convert:
  actions:
    - key: http.status_code
      action: convert
      converted_type: int


# The following demonstrates excluding spans from this attributes processor.
# Ex. The following spans match the properties and won't be processed by the
# processor.
# Span1 Name: 'svcB' Attributes: {env: dev, test_request: 123, credit_card: 1234}
# Span2 Name: 'svcA' Attributes: {env: dev, test_request: false}
# The following spans do not match the properties and the processor actions
# are applied to it.
# Span3 Name: 'svcB' Attributes: {env: 1, test_request: dev, credit_card: 1234}
# Span4 Name: 'svcC' Attributes: {env: dev, test_request: false}
attributes/excludemulti:
  # Specifies the spans properties that exclude a span from being processed.
  exclude:
    # match_type defines that "services" is an array of strings that must
    # match service name strictly.
    match_type: strict
    # The Span service name must be equal to "svcA" or "svcB".
    services: ["svcA", "svcB"]
    attributes:
      # This exact attribute ('env', 'dev') must exist in the span for a match.
      - {key: env, value: "dev"}
      # As long as there is an attribute with key 'test_request' in the span
      # there is a match.
      - {key: test_request}
  actions:
    - key: credit_card
      action: delete
    - key: duplicate_key
      action: delete

# The following demonstrates excluding spans from this attributes processor based on a resource.
attributes/excluderesources:
  # Specifies the spans properties that exclude a span from being processed.
  exclude:
    # match_type defines that "resources" is an map where values must match strictly.
    match_type: strict
    resources:
      # This exact resource ('host.type', 'n1-standard-1') must exist in the span for a match.
      - {key: host.type, value: "n1-standard-1"}
  actions:
    - key: credit_card
      action: delete
    - key: duplicate_key
      action: delete

# The following demonstrates excluding spans from this attributes processor based on an instrumenting library.
# If no version is provided, any version will match, even no version.
# If a blank version provided, only no version will match.
attributes/excludelibrary:
  # Specifies the spans properties that exclude a span from being processed.
  exclude:
    # match_type defines that "libraries" is an map where values must match strictly.
    match_type: strict
    libraries:
      # This exact library ('mongo-java-driver', version '3.8.0') must exist in the span for a match.
      - {name: "mongo-java-driver", version: "3.8.0"}
  actions:
    - key: credit_card
      action: delete
    - key: duplicate_key
      action: delete

# The following demonstrates including spans for this attributes processor.
# All other spans that do no match the properties are not processed
# by this processor.
# Ex. The following are spans match the properties and the actions are applied.
# Span1 Name: 'svcB' Attributes: {env: dev, test_request: 123, credit_card: 1234}
# Span2 Name: 'svcA' Attributes: {env: dev, test_request: false}
# Span3 Name: 'svcB' Attributes: {env: 1, test_request: dev, credit_card: 1234}
# The following span does not match the include properties and the
# processor actions are not applied.
# Span4 Name: 'svcC' Attributes: {env: dev, test_request: false}
attributes/includeservices:
  # Specifies the span properties that must exist for the processor to be applied.
  include:
    # match_type defines that "services" is an array of regexp-es.
    match_type: regexp
    # The Span service name must match "auth.*" or "login.*" regexp.
    services: ["auth.*", "login.*"]
  actions:
    - key: credit_card
      action: delete
    - key: duplicate_key
      action: delete

# The following demonstrates specifying the set of span properties to
# indicate which spans this processor should be applied to. The `include` of
# properties say which ones should be included and the `exclude` properties
# further filter out spans that shouldn't be processed.
# Ex. The following are spans match the properties and the actions are applied.
# Note this span is processed because the value type of redact_trace is a string instead of a boolean.
# Span1 Name: 'svcB' Attributes: {env: production, test_request: 123, credit_card: 1234, redact_trace: "false"}
# Span2 Name: 'svcA' Attributes: {env: staging, test_request: false, redact_trace: true}
# The following span does not match the include properties and the
# processor actions are not applied.
# Span3 Name: 'svcB' Attributes: {env: production, test_request: true, credit_card: 1234, redact_trace: false}
# Span4 Name: 'svcC' Attributes: {env: dev, test_request: false}
attributes/selectiveprocessing:
  # Specifies the span properties that must exist for the processor to be applied.
  include:
    # match_type defines that "services" is an array of strings that must
    # match service name strictly.
    match_type: strict
    # The Span service name must be equal to "svcA" or "svcB".
    services: ["svcA", "svcB"]
  exclude:
    # match_type defines that "attributes" values must match strictly.
    match_type: strict
    attributes:
      - { key: redact_trace, value: false}
  actions:
    - key: credit_card
      action: delete
    - key: duplicate_key
      action: delete

# The following demonstrates how to backfill spans missing an attribute,
# insert/update that value to a new key and deleting the old key. This guarantees
# an attribute `svc.operation` exists in spans and the attribute `operation`
# doesn't exist.
# Ex: The spans before the processor `attributes/complex`.
# Span1 Attributes: {timeout: 10, svc.operation: addition, operation: addition}
# Span2 Attributes: {operation: subtract, math_value: 123}
# Span3 Attributes: {timeout: 10, math_value: 4}
# Span4 Attributes: {svc.operation: division, timeout: 3}
attributes/complex:
  # Note: There are no include and exclude settings so all spans are processed.
  actions:
    - key: operation
      value: default
      action: insert
    # The spans after the first action of insert.
    # Span1 Attributes: {timeout: 10, svc.operation: addition, operation: addition}
    # Span2 Attributes: {operation: subtract, math_value: 123}
    # Span3 Attributes: {timeout: 10, math_value: 4, operation: default}
    # Span4 Attributes: {svc.operation: division, timeout: 3, operation:default}

    - key: svc.operation
      from_attribute: operation
      action: upsert
    # The spans after the second action of upsert.
    # Span1 Attributes: {timeout: 10, svc.operation: addition, operation: addition}
    # Span2 Attributes: {svc.operation: subtract, operation: subtract, math_value: 123}
    # Span3 Attributes: {svc.operation: default, timeout: 10, math_value: 4, operation: default}
    # Span4 Attributes: {svc.operation: default, timeout: 3, operation:default}

    - key: operation
      action: delete
    # The spans after the third/final action of delete.
    # Span1 Attributes: {timeout: 10, svc.operation: addition}
    # Span2 Attributes: {svc.operation: subtract, math_value: 123}
    # Span3 Attributes: {svc.operation: default, timeout: 10, math_value: 4}
    # Span4 Attributes: {svc.operation: default, timeout: 3}

# The following is an example of various actions. The actions are applied in
# the order specified in the configuration.
attributes/example:
  actions:
    - key: db.table
      action: delete
    - key: redacted_span
      value: true
      action: upsert
    - key: copy_key
      from_attribute: key_original
      action: update
    - key: account_id
      value: 2245
      action: insert
    - key: account_password
      action: delete

# The following demonstrates how to process spans that have a service name and span
# name that match regexp patterns. This processor will remove "token" attribute
# and will obfuscate "password" attribute in spans where service name matches "auth.*"
# and where span name does not match "login.*".
attributes/regexp:
  # Specifies the span properties that must exist for the processor to be applied.
  include:
    # match_type defines that "services" is an array of regexp-es.
    match_type: regexp
    # The span service name must match "auth.*" pattern.
    services: ["auth.*"]
  exclude:
    # match_type defines that "span_names" is an array of regexp-es.
    match_type: regexp
    # The span name must not match "login.*" pattern.
    span_names: ["login.*"]
  actions:
    - key: password
      action: update
      value: "obfuscated"
    - key: token
      action: delete

# The following demonstrates how to process spans that have an attribute that matches a regexp patterns.
# This processor will obfuscate "db.statement" attribute in spans where "db.statement attribute
# matches a regex pattern.
attributes/regexp2:
  # Specifies the span properties that must exist for the processor to be applied.
  include:
    # match_type defines that "attributes" is a map where values are regexp-es.
    match_type: regexp
    attributes:
      # This attribute ('db.statement') must exist in the span and match the regex ('SELECT \* FROM USERS.*') for a match.
      - {key: "db.statement", value: 'SELECT \* FROM USERS.*'}
  actions:
    - key: db.statement
      action: update
      value: "SELECT * FROM USERS [obfuscated]"


# The following demonstrates how to process logs that have a body that match regexp
# patterns. This processor will remove "token" attribute and will obfuscate "password"
# attribute in spans where body matches "AUTH.*".
attributes/log_body_regexp:
  # Specifies the span properties that must exist for the processor to be applied.
  include:
    # match_type defines that "services" is an array of regexp-es.
    match_type: regexp
    # The span service name must match "auth.*" pattern.
    log_bodies: ["AUTH.*"]
  actions:
    - key: password
      action: update
      value: "obfuscated"
    - key: token
      action: delete

# The following demonstrates how to process logs that have a severity text that match regexp
# patterns. This processor will remove "token" attribute and will obfuscate "password"
# attribute in spans where severity matches "debug".
attributes/log_severity_regexp:
  # Specifies the span properties that must exist for the processor to be applied.
  include:
    # match_type defines that "services" is an array of regexp-es.
    match_type: regexp
    # The log severity text "debug.*" pattern.
    log_severity_texts: [ "debug.*" ]
  actions:
    - key: password
      action: update
      value: "obfuscated"
    - key: token
      action: delete

attributes/from_context:
  actions:
  - key: origin
    from_context: metadata.origin
    action: insert
  - key: enduser.id
    # The following uses `subject` attribute produced
    # by the server authenticator from `oidc` extension
    # to set the identity of an exporter on spans.
    # Refer to the server authenticator's documentation part of your pipeline
    # for more information about which attributes are available.
    from_context: auth.subject
    action: insert

attributes/servicesmetrics:
  include:
    match_type: strict
    services:
      - foo
  actions:
    - key: service.name
      value: bar
      action: insert

# The following demonstrates using default_value to handle missing environment variables or attributes
attributes/with_defaults:
  actions:
  # Use default when source attribute doesn't exist
  - key: service.namespace
    from_attribute: namespace
    default_value: "default"
    action: insert
  # Use default when context value is not available
  - key: cloud.region
    from_context: "metadata.region"
    default_value: "us-east-1"
    action: upsert

Last generated: 2026-08-24

​Attributes Processor

​Supported Telemetry

​Overview

​Default Values

​Attributes Processor for Metrics vs. Metric Transform Processor

​Include/Exclude Filtering

​Match Configuration

​Warnings

​Configuration

​Example Configuration