Add ECS conversion tables

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'

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 ECS fields. If an attribute doesn't have a predefined ECS 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.

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) |
+| **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
+```

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)

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