docs: add opentelemetry mapping (#7579)

The OpenTelemetry API support implements a mapping from OpenTelemetry to
Datadog spans. The documentation changes here are to represent the
mapping, specifically for attributes to tags.

Preview:

<img width="846" alt="image"
src="https://github.com/DataDog/dd-trace-py/assets/155673/6534eb7c-f350-45ba-ac2e-5bcd04f1a4ec">

 
## Checklist

- [x] Change(s) are motivated and described in the PR description.
- [x] Testing strategy is described if automated tests are not included
in the PR.
- [x] Risk is outlined (performance impact, potential for breakage,
maintainability, etc).
- [x] Change is maintainable (easy to change, telemetry, documentation).
- [x] [Library release note
guidelines](https://ddtrace.readthedocs.io/en/stable/releasenotes.html)
are followed. If no release note is required, add label
`changelog/no-changelog`.
- [x] Documentation is included (in-code, generated user docs, [public
corp docs](https://github.com/DataDog/documentation/)).
- [x] Backport labels are set (if
[applicable](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting))

## Reviewer Checklist

- [x] Title is accurate.
- [x] No unnecessary changes are introduced.
- [x] Description motivates each change.
- [x] Avoids breaking
[API](https://ddtrace.readthedocs.io/en/stable/versioning.html#interfaces)
changes unless absolutely necessary.
- [x] Testing strategy adequately addresses listed risk(s).
- [x] Change is maintainable (easy to change, telemetry, documentation).
- [x] Release note makes sense to a user of the library.
- [x] Reviewer has explicitly acknowledged and discussed the performance
implications of this PR as reported in the benchmarks PR comment.
- [x] Backport labels are set in a manner that is consistent with the
[release branch maintenance
policy](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting)
- [x] If this PR touches code that signs or publishes builds or
packages, or handles credentials of any kind, I've requested a review
from `@DataDog/security-design-and-guidance`.
- [x] This PR doesn't touch any of that.

Author: majorgreys

ddtrace/opentelemetry/__init__.py

@@ -3,7 +3,7 @@
 =================
 
 The dd-trace-py library provides an implementation of the
-`opentelemetry api <https://opentelemetry-python.readthedocs.io/en/latest/api/index.html>`_.
+`OpenTelemetry API <https://opentelemetry-python.readthedocs.io/en/latest/api/index.html>`_.
 When ddtrace OpenTelemetry support is configured, all operations defined in the
 OpenTelemetry trace api can be used to create, configure, and propagate a distributed trace.
 All operations defined the opentelemetry trace api are configured to use the ddtrace global tracer (``ddtrace.tracer``)
@@ -51,7 +51,61 @@
     @oteltracer.start_as_current_span("span_name")
     def some_function():
         pass
-"""
+
+
+Mapping
+-------
+
+The OpenTelemetry API support implementation maps OpenTelemetry spans to Datadog spans. This mapping is described by the following table, using the protocol buffer field names used in `OpenTelemetry <https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L80>`_ and `Datadog <https://github.com/DataDog/datadog-agent/blob/dc4958d9bf9f0e286a0854569012a3bd3e33e968/pkg/proto/datadog/trace/span.proto#L7>`_.
+
+
+.. list-table::
+    :header-rows: 1
+    :widths: 30, 30, 40
+
+    * - OpenTelemetry
+      - Datadog
+      - Description
+    * - ``trace_id``
+      - ``traceID``
+      -
+    * - ``span_id``
+      - ``spanID``
+      -
+    * - ``trace_state``
+      - ``meta["_sampling_priority_v1"]``, ``meta["_dd.origin"]``, ...
+      - Datadog vendor-specific data is set in trace state using the ``dd=`` prefix
+    * - ``parent_span_id``
+      - ``parentID``
+      -
+    * - ``name``
+      - ``name``
+      -
+    * - ``kind``
+      - ``meta["span.kind"]``
+      -
+    * - ``start_time_unix_nano``
+      - ``start``
+      -
+    * - ``end_time_unix_nano``
+      - ``duration``
+      - Derived from start and end time
+    * - ``attributes[<key>]``
+      - ``meta[<key>]``
+      - Datadog tags (``meta``) are set for each OpenTelemetry attribute
+    * - ``links[]``
+      - ``meta["_dd.span_links"]``
+      -
+    * - ``status``
+      - ``error``
+      - Derived from status
+    * - ``events[]``
+      - N/A
+      - Span events not supported on the Datadog platform
+
+
+"""  # noqa: E501
+
 from ._trace import TracerProvider
 
 

ddtrace/opentelemetry/_span.py

@@ -30,7 +30,10 @@
 
 
 class Span(OtelSpan):
-    """Initializes an Open Telemetry compatible shim for a datadog span"""
+    """Initializes an OpenTelemetry compatible shim for a Datadog span
+
+    TODO: Add mapping table from otel to datadog
+    """
 
     _RECORD_EXCEPTION_KEY = "_dd.otel.record_exception"
     _SET_EXCEPTION_STATUS_KEY = "_dd.otel.set_status_on_exception"
@@ -140,8 +143,9 @@ def update_name(self, name):
         """Updates the name of a span"""
         if not self.is_recording():
             return
-        # Open Telemetry spans have one name while Datadog spans can have two different names (operation and resource).
-        # Ensure the resource and operation names are equal for Open Telemetry spans
+        # OpenTelemetry spans have one name while Datadog spans can have two different names (operation and resource).
+        # Ensure the resource and operation names are equal for OpenTelemetry spans
+        #
         self._ddspan.name = name
         self._ddspan.resource = name
 

ddtrace/opentelemetry/_trace.py

@@ -57,7 +57,7 @@ def get_tracer(
 
 
 class Tracer(OtelTracer):
-    """Starts and/or activates Open Telemetry compatible Spans using the global Datadog Tracer."""
+    """Starts and/or activates OpenTelemetry compatible Spans using the global Datadog Tracer."""
 
     def __init__(self, datadog_tracer):
         # type: (DDTracer) -> None