diff --git a/redirects.yml b/redirects.yml index 3654bef773..53f380c041 100644 --- a/redirects.yml +++ b/redirects.yml @@ -33,7 +33,8 @@ redirects: 'solutions/observability/apps/upstream-opentelemetry-collectors-language-sdks.md': 'solutions/observability/apm/upstream-opentelemetry-collectors-language-sdks.md' 'solutions/observability/apps/collect-metrics.md': 'solutions/observability/apm/collect-metrics.md' 'solutions/observability/apps/limitations.md': 'solutions/observability/apm/limitations.md' - 'solutions/observability/apps/resource-atrributes.md': 'solutions/observability/apm/resource-attributes.md' + 'solutions/observability/apps/resource-atrributes.md': 'solutions/observability/apm/attributes.md' + 'solutions/observability/apps/resource-attributes.md': 'solutions/observability/apm/attributes.md' 'solutions/observability/apps/apm-k8s-attacher.md': 'solutions/observability/apm/apm-k8s-attacher.md' 'solutions/observability/apps/monitoring-aws-lambda-functions.md': 'solutions/observability/apm/monitor-aws-lambda-functions.md' 'solutions/observability/apps/integrate-with-jaeger-deprecated.md': 'solutions/observability/apm/jaeger.md' diff --git a/solutions/observability/apm/attributes.md b/solutions/observability/apm/attributes.md new file mode 100644 index 0000000000..3282c8ea6d --- /dev/null +++ b/solutions/observability/apm/attributes.md @@ -0,0 +1,84 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/observability/current/apm-open-telemetry-resource-attributes.html + - https://www.elastic.co/guide/en/serverless/current/observability-apm-agents-opentelemetry-resource-attributes.html +applies_to: + stack: + serverless: +--- + +# Attributes and labels [apm-open-telemetry-resource-attributes] + +In OpenTelemetry, an attribute is a key-value pair. Attributes are similar to [labels](/solutions/observability/apm/metadata.md#apm-data-model-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. + +## Setting resource attributes + +You can set resource attributes through environment variables or by editing the configuration of the resource processor of the OpenTelemetry Collector. + +### OpenTelemetry agent + +Use the `OTEL_RESOURCE_ATTRIBUTES` environment variable to pass resource attributes at process invocation. For example: + +```bash +export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production +``` + +### OpenTelemetry Collector + +Use the [resource processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourceprocessor) to set or apply changes to resource attributes when using the OTel Collector. + +```yaml +... +processors: + resource: + attributes: + - key: deployment.environment + action: insert + value: production +... +``` + +## Handling of unmapped attributes + +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: + +```json +{ + "service.name": "user-service", + "deployment.environment": "production", + "otel.library.name": "my-lib", + "custom.attribute.with.dots": "value" +} +``` + +Elastic APM stores the following: + +```json +{ + "service.name": "user-service", + "service.environment": "production", + "labels": { + "otel_library_name": "my-lib", + "custom_attribute_with_dots": "value" + } +} +``` + +## Scope attributes translation + +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. \ No newline at end of file diff --git a/solutions/observability/apm/resource-attributes.md b/solutions/observability/apm/resource-attributes.md deleted file mode 100644 index 3aa493419b..0000000000 --- a/solutions/observability/apm/resource-attributes.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -mapped_pages: - - https://www.elastic.co/guide/en/observability/current/apm-open-telemetry-resource-attributes.html - - https://www.elastic.co/guide/en/serverless/current/observability-apm-agents-opentelemetry-resource-attributes.html -applies_to: - stack: - serverless: ---- - -# Resource attributes [apm-open-telemetry-resource-attributes] - -A resource attribute is a key/value pair containing information about the entity producing telemetry. Resource attributes are mapped to Elastic Common Schema (ECS) fields like `service.*`, `cloud.*`, `process.*`, etc. These fields describe the service and the environment that the service runs in. - -The examples shown here set the Elastic (ECS) `service.environment` field for the resource, i.e. service, that is producing trace events. Note that Elastic maps the OpenTelemetry `deployment.environment` field to the ECS `service.environment` field on ingestion. - -**OpenTelemetry agent** - -Use the `OTEL_RESOURCE_ATTRIBUTES` environment variable to pass resource attributes at process invocation. - -```bash -export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production -``` - -**OpenTelemetry collector** - -Use the [resource processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourceprocessor) to set or apply changes to resource attributes. - -```yaml -... -processors: - resource: - attributes: - - key: deployment.environment - action: insert - value: production -... -``` - -::::{tip} -Need to add event attributes instead? Use attributes—​not to be confused with resource attributes—​to add data to span, log, or metric events. Attributes can be added as a part of the OpenTelemetry instrumentation process or with the [attributes processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/attributesprocessor). - -:::: - -% Stateful only after this? - -Elastic integrates with OpenTelemetry, allowing you to reuse your existing instrumentation to easily send observability data to the {{stack}}. - -For more information on how to combine Elastic and OpenTelemetry, see [OpenTelemetry integration](/solutions/observability/apm/use-opentelemetry-with-apm.md). \ No newline at end of file diff --git a/solutions/observability/apm/spans.md b/solutions/observability/apm/spans.md index 03cb98f025..1f26a7aff7 100644 --- a/solutions/observability/apm/spans.md +++ b/solutions/observability/apm/spans.md @@ -475,4 +475,49 @@ Support for span compression is available in the following agents and can be con | **Java agent** | [`span_compression_same_kind_max_duration`](apm-agent-java://reference/config-huge-traces.md#config-span-compression-same-kind-max-duration) | [`span_compression_exact_match_max_duration`](apm-agent-java://reference/config-huge-traces.md#config-span-compression-exact-match-max-duration) | | **.NET agent** | [`SpanCompressionSameKindMaxDuration`](apm-agent-dotnet://reference/config-core.md#config-span-compression-exact-match-max-duration) | | **Node.js agent** | [`spanCompressionSameKindMaxDuration`](apm-agent-nodejs://reference/configuration.md#span-compression-exact-match-max-duration) | -| **Python agent** | [`span_compression_same_kind_max_duration`](apm-agent-python://reference/configuration.md#config-span-compression-exact-match-max_duration) | \ No newline at end of file +| **Python agent** | [`span_compression_same_kind_max_duration`](apm-agent-python://reference/configuration.md#config-span-compression-exact-match-max_duration) | + +## OpenTelemetry and Elastic APM spans + +OpenTelemetry spans are mapped to Elastic APM transactions and spans as follows: + +- Root spans, such as entry points, are mapped to APM transactions. +- Child spans, such as internal operations and DB queries, are mapped to APM spans. + +The following table summarizes the mapping between OpenTelemetry span kinds and Elastic APM entities. + +| OpenTelemetry span kind | Mapped to APM | Example | +|-------------------------|---------------|---------| +| `SERVER` | Transaction | Incoming HTTP request (`GET /users/{id}`) | +| `CONSUMER` | Transaction | Message queue consumer event | +| `CLIENT` | Span | Outgoing database query (`SELECT * FROM users`) | +| `PRODUCER` | Span | Sending a message to a queue | +| `INTERNAL` | Span | Internal function execution | + +The following example shows OpenTelemetry spans: + +```json +[ + { + "traceId": "abcd1234", + "spanId": "root5678", + "parentId": null, + "name": "GET /users/{id}", + "kind": "SERVER" + }, + { + "traceId": "abcd1234", + "spanId": "db1234", + "parentId": "root5678", + "name": "SELECT FROM users", + "kind": "CLIENT" + } +] +``` + +The previous OTel spans are stored by Elastic APM as follows: + +``` +Transaction: GET /users/{id} + ├── Span: SELECT FROM users +``` diff --git a/solutions/observability/apm/upstream-opentelemetry-collectors-language-sdks.md b/solutions/observability/apm/upstream-opentelemetry-collectors-language-sdks.md index 065fec81d2..65dc000f13 100644 --- a/solutions/observability/apm/upstream-opentelemetry-collectors-language-sdks.md +++ b/solutions/observability/apm/upstream-opentelemetry-collectors-language-sdks.md @@ -175,7 +175,7 @@ java -javaagent:/path/to/opentelemetry-javaagent-all.jar \ 1. [preview] The OpenTelemetry logs intake via APM Server is currently in technical preview. `OTEL_RESOURCE_ATTRIBUTES` -: Fields that describe the service and the environment that the service runs in. See [resource attributes](/solutions/observability/apm/resource-attributes.md) for more information. +: Fields that describe the service and the environment that the service runs in. See [attributes](/solutions/observability/apm/attributes.md) for more information. `OTEL_EXPORTER_OTLP_ENDPOINT` : APM Server URL. The host and port that APM Server listens for events on. @@ -216,7 +216,7 @@ java -javaagent:/path/to/opentelemetry-javaagent-all.jar \ 1. [preview] The OpenTelemetry logs intake via Elastic is currently in technical preview. `OTEL_RESOURCE_ATTRIBUTES` -: Fields that describe the service and the environment that the service runs in. See [resource attributes](/solutions/observability/apm/resource-attributes.md) for more information. +: Fields that describe the service and the environment that the service runs in. See [attributes](/solutions/observability/apm/attributes.md) for more information. `OTEL_EXPORTER_OTLP_ENDPOINT` : Elastic URL. The host and port that Elastic listens for APM events on. @@ -265,5 +265,5 @@ For more information on how APM Server services gRPC requests, see [Muxing gRPC ## Next steps [apm-open-telemetry-direct-next] * [Collect metrics](/solutions/observability/apm/collect-metrics.md) -* Add [Resource attributes](/solutions/observability/apm/resource-attributes.md) +* Add [resource attributes](/solutions/observability/apm/attributes.md) * Learn about the [limitations of this integration](/solutions/observability/apm/limitations.md) diff --git a/solutions/toc.yml b/solutions/toc.yml index fd15276e5c..e202a9c385 100644 --- a/solutions/toc.yml +++ b/solutions/toc.yml @@ -131,7 +131,7 @@ toc: - file: observability/apm/upstream-opentelemetry-collectors-language-sdks.md - file: observability/apm/collect-metrics.md - file: observability/apm/limitations.md - - file: observability/apm/resource-attributes.md + - file: observability/apm/attributes.md - file: observability/apm/apm-k8s-attacher.md - file: observability/apm/monitor-aws-lambda-functions.md - file: observability/apm/jaeger.md