Python Custom Instrumentation using the OpenTelemetry API

このページは日本語には対応しておりません。随時翻訳に取り組んでいます。翻訳に関してご質問やご意見ございましたら、お気軽にご連絡ください。
Datadog で OpenTelemetry を使用するタイミングがわからない場合は、OpenTelemetry API を使用したカスタムインスツルメンテーションから始めて、詳細を学びましょう。

概要

OpenTelemetry API を使用してアプリケーションを手動でインスツルメントする理由はいくつかあります。

ddtrace ライブラリは、これらの目標を達成するためのさまざまなテクニックを提供しています。次のセクションでは、Datadog で使用するために OpenTelemetry API を使用してカスタムインスツルメンテーションを行う方法を説明します。

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

Adding span events requires SDK version 2.9.0 or higher.

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

お役に立つドキュメント、リンクや記事:

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