Overview

There are a few reasons to manually instrument your applications with the OpenTelemetry API:

• You are not using Datadog supported library instrumentation.
• You want to extend the ddtrace library’s functionality.
• You need finer control over instrumenting your applications.

The ddtrace library provides several techniques to help you achieve these goals. The following sections demonstrate how to use the OpenTelemetry API for custom instrumentation to use with Datadog.

Setup

To configure OpenTelemetry to use the Datadog trace provider:

1. If you have not yet read the instructions for auto-instrumentation and setup, start with the Python Setup Instructions.

2. Set DD_TRACE_OTEL_ENABLED environment variable to true.

Creating custom spans

To create custom spans within an existing trace context:

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

def do_work():
    with tracer.start_as_current_span("operation_name") as span:
        # Perform the work that you want to track with the span
        print("Doing work...")
        # When the 'with' block ends, the span is automatically closed

Accessing active spans

To access the currently active span, use the get_current_span() function:

from opentelemetry import trace

current_span = trace.get_current_span()
# enrich 'current_span' with information

Adding span tags

Add attributes to a span to provide additional context or metadata.

Here’s an example of how to add attributes to the current span:

from opentelemetry import trace

current_span = trace.get_current_span()

current_span.set_attribute("attribute_key1", 1)

Adding span events

Minimum SDK version: 2.9.0.

You can add span events using the add_event API. This method requires a name parameter and optionally accepts attributes and timestamp parameters. The method creates a new span event with the specified properties and associates it with the corresponding span.

• Name [required]: A string representing the event’s name.
• Attributes [optional]: Zero or more key-value pairs with the following properties:
  • The key must be a non-empty string.
  • The value can be either:
    • A primitive type: string, Boolean, or number.
    • A homogeneous array of primitive type values (for example, an array of strings).
  • Nested arrays and arrays containing elements of different data types are not allowed.
• Timestamp [optional]: A UNIX timestamp representing the event’s occurrence time, expects microseconds.

The following examples demonstrate different ways to add events to a span:

span.add_event("Event With No Attributes")
span.add_event("Event With Some Attributes", {"int_val": 1, "string_val": "two", "int_array": [3, 4], "string_array": ["5", "6"], "bool_array": [True, False]})

Read the OpenTelemetry specification for more information.

Recording exceptions

To record exceptions, use the record_exception API. This method requires an exception parameter and optionally accepts a UNIX timestamp parameter. It creates a new span event that includes standardized exception attributes and associates it with the corresponding span.

The following examples demonstrate different ways to record exceptions:

span.record_exception(Exception("Error Message"))
span.record_exception(Exception("Error Message"), {"status": "failed"})

Read the OpenTelemetry specification for more information.

Further reading

Additional helpful documentation, links, and articles:

Explore your services, resources, and tracesDOCUMENTATION Interoperability of OpenTelemetry API and Datadog instrumented tracesDOCUMENTATION