Attributes and labels

In OpenTelemetry, an attribute is a key-value pair. Attributes are similar to labels in that they add metadata to transactions, spans, and other entities.

Important

This page describes how attributes are handled when sending OTLP data to APM Server or managed inputs (the .apm endpoint), a legacy ingest path. On this path, attributes are mapped to ECS fields, and unmapped attributes are stored under labels.*.

For new users, Elastic recommends the Elastic Cloud Managed OTLP Endpoint or Elastic Agent configured as an OTel Collector instead. On those paths, your data is stored in OTel-native format, and attributes are preserved under resource.attributes.* and attributes.*. For a comparison of both formats and guidance on choosing your ingest path, refer to How your ingest path determines the data format.

Resource attributes are a type of attribute that contains information about the entities that produce telemetry. Resource attributes map to Elastic Common Schema (ECS) fields like service.*, cloud.*, process.*, and so on. These fields describe the service and its environment.

For example, Elastic APM maps the OpenTelemetry deployment.environment field to the ECS service.environment field on ingestion.

Note

The deployment.environment attribute populates the environment selector in the Kibana APM Service Map. Without it, services appear under an "unset" environment, meaning you can't distinguish between production, staging, or other environments using the selector. Set this attribute at the Collector level using the resource processor so it applies consistently to all telemetry from your services.

You can set resource attributes through environment variables or by editing the configuration of the resource processor of the OpenTelemetry Collector.

Use the OTEL_RESOURCE_ATTRIBUTES environment variable to pass resource attributes at process invocation. For example:

export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production

Use the resource processor to set or apply changes to resource attributes when using Elastic Agent.

...
processors:
  resource:
    attributes:
    - key: deployment.environment
      action: insert
      value: production
...

When sending telemetry to Elastic APM, only a subset of OpenTelemetry attributes are directly mapped to Elastic APM document fields, such as ECS fields. If an attribute doesn't have a predefined mapping, the system stores it under labels.*, with dots replaced by underscores.

Unmapped resource attributes are treated as global labels in Elastic APM, meaning they apply to all telemetry data from the resource. In contrast, unmapped record-level attributes, such as those specific to a log record, span, or data point, are stored as normal labels associated only with that specific record.

For example, if an OpenTelemetry resource contains:

{
  "service.name": "user-service",
  "deployment.environment": "production",
  "otel.library.name": "my-lib",
  "custom.attribute.with.dots": "value"
}

Elastic APM stores the following:

{
  "service.name": "user-service",
  "service.environment": "production",
  "labels": {
    "otel_library_name": "my-lib",
    "custom_attribute_with_dots": "value"
  }
}

Scope attributes are translated as follows:

OpenTelemetry attribute Elastic APM field
scope.name service.framework.name
scope.version service.framework.version

Unmapped scope attributes are ignored.