Add ECS conversion tables

solutions/observability/apm/resource-attributes.md

@@ -9,21 +9,25 @@ applies_to:
 
 # 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.
+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.*`, and so on. 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.
+The examples set the Elastic (ECS) `service.environment` field for the resource that's producing trace events. Elastic maps the OpenTelemetry `deployment.environment` field to the ECS `service.environment` field on ingestion.
 
-**OpenTelemetry agent**
+## Setting resource attributes
 
-Use the `OTEL_RESOURCE_ATTRIBUTES` environment variable to pass resource attributes at process invocation.
+You can set resource attributes through the environment variables or by editing the configuration of the resource processor of the 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**
+### 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.
+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
 ...
@@ -36,13 +40,63 @@ processors:
 ...
 ```
 
-::::{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).
+## Handling of unmapped attributes
+
+Only a subset of OpenTelemetry resource attributes are directly mapped to ECS fields. If an attribute doesn't have a predefined ECS mapping, the systems stores it under `labels.*`, with dots replaced by underscores.
+
+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"
+  }
+}
+```
 
-% Stateful only after this?
+## Scope attributes translation
+
+Scope attributes are translated as follows:
+
+| OpenTelemetry attribute | Elastic APM field |
+|-------------------------|-------------------|
+| scope.name | service.framework.name |
+| scope.version | service.framework.version |
+
+## Conditional attributes translation
+
+Some OpenTelemetry attributes are conditionally converted based on their value type.
+
+Consider the following resource attributes:
+
+```json
+{
+  "http.status_code": 200,
+  "feature.enabled": true
+}
+```
 
-Elastic integrates with OpenTelemetry, allowing you to reuse your existing instrumentation to easily send observability data to the {{stack}}.
+The previous resource attributes are stored by Elastic APM as follows:
 
-For more information on how to combine Elastic and OpenTelemetry, see [OpenTelemetry integration](/solutions/observability/apm/use-opentelemetry-with-apm.md).
+```json
+{
+  "http.response.status_code": 200,
+  "labels": {
+    "feature_enabled": true
+  }
+}
+```

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