OpenTelemetry API を使った Python カスタムインスツルメンテーション

Unsure when to use OpenTelemetry with Datadog? Start with Custom Instrumentation with the OpenTelemetry API to learn more.

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.

セットアップ

OpenTelemetry を Datadog トレースプロバイダーを使用するように構成するには

  1. 自動インスツルメンテーションとセットアップの説明をまだお読みでない場合は、Python セットアップ手順からお読みください。

  2. DD_TRACE_OTEL_ENABLED 環境変数を true に設定します。

カスタムスパンの作成

既存のトレースコンテキスト内にカスタムスパンを作成するには

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

def do_work():
    with tracer.start_as_current_span("operation_name") as span:
        # スパンで追跡したい作業を実行
        print("Doing work...")
        # 'with' ブロックが終了すると、スパンは自動的に閉じる

アクティブなスパンへのアクセス

現在アクティブなスパンにアクセスするには、get_current_span() 関数を使います。

from opentelemetry import trace

current_span = trace.get_current_span()
# 'current_span' に情報を追加

スパンタグの追加

スパンに属性を追加して、追加のコンテキストやメタデータを提供します。

以下は、現在のスパンに属性を追加する方法の例です。

from opentelemetry import trace

current_span = trace.get_current_span()

current_span.set_attribute("attribute_key1", 1)

スパン イベントの追加

スパン イベントを追加するには SDK バージョン 2.9.0 以上が必要です。

add_event API を使用してスパン イベントを追加できます。このメソッドには必須パラメーター name があり、オプションで attributes と timestamp を受け取ります。メソッドは指定されたプロパティを持つ新しいスパン イベントを作成し、対象のスパンに関連付けます。

  • Name [required]: イベント名を表す文字列。
  • Attributes [optional]: 以下のプロパティを持つ 0 個以上のキーと値のペア。
    • キーは空でない文字列である必要があります。
    • 値として指定できるのは次のいずれかです。
      • プリミティブ型: string、Boolean、number。
      • 同一プリミティブ型の要素のみを含む配列 (例: string の配列)。
    • 入れ子の配列や異なるデータ型を混在させた配列は使用できません。
  • Timestamp [optional]: イベント発生時刻を表す UNIX タイムスタンプ。microseconds を想定します。

以下の例は、スパンにイベントを追加するさまざまな方法を示しています。

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]})

詳細は OpenTelemetry 仕様 を参照してください。

例外の記録

例外を記録するには record_exception API を使用します。このメソッドには必須パラメーター exception があり、オプションで UNIX timestamp を受け取ります。標準化された例外属性を含む新しいスパン イベントを作成し、対象のスパンに関連付けます。

以下の例は、例外を記録するさまざまな方法を示しています。

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

詳細は OpenTelemetry 仕様 を参照してください。

参考資料

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

サービス、リソース、トレースの詳細ドキュメント more more OpenTelemetry API と Datadog でインスツルメントされたトレースの相互運用性ドキュメント more more