Attributes and labels

Elastic Stack Serverless

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.

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.

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 the OTel Collector.

...
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:

Unmapped scope attributes are ignored.