Python のカスタムインスツルメンテーション
Dash が新機能を発表!インシデントマネジメント、Continuous Profiler など多数の機能が追加されました! Dash イベントで発表された新機能!

Python のカスタムインスツルメンテーション

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

対応するライブラリインスツルメンテーションを使用しない場合( ライブラリの互換性参照)、手動でコードをインスツルメントする必要があります。

ddtrace ライブラリの機能性を拡張したり、アプリケーションのインスツルメントをより精確に制御するのに役立つ方法がライブラリにあります。

スパンの作成

ddtrace ライブラリは、ddtrace-run多くのライブラリとフレームワークに対応するスパンを自動生成します。しかし、使用しているコードを可視化したい場合はスパンの利用が便利です。

Web リクエスト (例: make_sandwich_request) 内で、get_ingredients()assemble_sandwich() など、測定に役立つさまざまなオペレーションを行うことができます。

def make_sandwich_request(request):
    ingredients = get_ingredients()
    sandwich = assemble_sandwich(ingredients)

ddtrace から提供される tracer.wrap() デコレータを使用して、対象の関数を修飾することができます。呼び出し場所に関わらずに関数をトレースしたい場合に便利です。

  from ddtrace import tracer

  @tracer.wrap()
  def get_ingredients():
      # パントリーに行く
      # 冷蔵庫の中身を確認
      # 足りないものは買い出し
      return

  # スパンのカスタマイズに必要な情報を共有
  @tracer.wrap("assemble_sandwich", service="my-sandwich-making-svc")
  def assemble_sandwich(ingredients):
      return

ddtrace.Tracer.wrap() 向けデコレータの API 詳細は、こちらで確認できます。

任意のコードブロックをトレースするには、以下の ddtrace.Span コンテキストマネージャーを使用するか、 高度な使用方法に関するドキュメントを参照してください。

from ddtrace import tracer

def make_sandwich_request(request):
    # スパンで両方のオペレーションを取得
    with tracer.trace("sandwich.make"):
        ingredients = get_ingredients()
        sandwich = assemble_sandwich(ingredients)

def make_sandwich_request(request):
    # スパンで両方のオペレーションを取得
    with tracer.trace("sandwich.create") as outer_span:
        with tracer.trace("get_ingredients") as span:
            ingredients = get_ingredients()

        with tracer.trace("assemble_sandwich") as span:
            sandwich = assemble_sandwich(ingredients)

ddtrace.Tracer() の API 詳細はこちらで確認できます

デコレータおよびコンテキストマネージャー以外のトレーシング方法として、スパンの開始と終了を可能にする手動 API があります。これに必要なのは、

def make_sandwich_request(request):
    span = tracer.trace("sandwich.create")
    ingredients = get_ingredients()
    sandwich = assemble_sandwich(ingredients)
    span.finish()  # ここでスパンを閉じる

デコレータの API 詳細は、ddtrace.Tracer.traceドキュメントまたは ddtrace.Span.finishドキュメントで確認できます。

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

内蔵のインスツルメンテーションおよびカスタムインスツルメンテーションは、有意義なオペレーションに関連するスパンを作成します。アクティブなスパンにアクセスして、これらの有意義なデータを含めるよう設定できます。

from ddtrace import tracer

def make_sandwich_request(request):
    # スパンで両方のオペレーションを取得
    with tracer.trace("sandwich.make") as my_span:
        ingredients = get_ingredients()
        sandwich = assemble_sandwich(ingredients)
def get_ingredients():
    # アクティブなスパンを取得
    span = tracer.current_span()
    # 上記の make_sandwich_request からの my_span
def assemble_sandwich(ingredients):
    with tracer.trace("another.operation") as another_span:
        # アクティブなルートスパンを取得
        span = tracer.current_root_span()
        # 上記の make_sandwich_request からの my_span

タグの追加

スパンに set_tag メソッドを適用して、スパンにタグを追加することができます。

from ddtrace import tracer

def make_sandwich_request(request):
    with tracer.trace("sandwich.make") as span:
        ingredients = get_ingredients()
        span.set_tag("num_ingredients", len(ingredients))

タグはトレーサー上にグローバルに設定することができます。これらのタグは作成されるスパンのそれぞれに適用されます。

from ddtrace import tracer
from myapp import __version__

# これは各スパンに適用されます
tracer.set_tags({"version": __version__, "<TAG_KEY_2>": "<TAG_VALUE_2>"})

例外発生時点でアクティブなスパンが存在した場合は、その例外の情報がスパンに添付されます。

from ddtrace import tracer

with tracer.trace("throws.an.error") as span:
    raise Exception("Oops!")

# `span` にエラーフラグを立て、
# スタックトレースと例外メッセージをタグとして追加

スパンへのエラーフラグ適用は、手動でも行うことができます。

from ddtrace import tracer

span = tracer.trace("operation")
span.error = 1
span.finish()

リソースフィルター

トレースはそれぞれのリソース名に基づいて除外可能で、これによりヘルスチェックなどの外形監視トラフィックが Datadog にレポートされるトレースから削除されます。この設定およびその他のセキュリティ/微調整に関するコンフィギュレーションについてはセキュリティページを参照してください。

OpenTracing

OpenTracing のサポートは ddtrace パッケージに含まれています。pip を使用して、必要な opentracing パッケージをインストールします。

pip install ddtrace[opentracing]

トレーサーを初期化するための OpenTracing の規則は、新しいトレーサーを構成、インスタンス化し、グローバルな opentracing.tracer 参照を上書きする初期化メソッドを定義することです。

import time
import opentracing
from ddtrace.opentracer import Tracer, set_global_tracer

def init_tracer(service_name):
    config = {
      "agent_hostname": "localhost",
      "agent_port": 8126,
    }
    tracer = Tracer(service_name, config=config)
    set_global_tracer(tracer)
    return tracer

def my_operation():
  span = opentracing.tracer.start_span("<OPERATION_NAME>")
  span.set_tag("<TAG_KEY>", "<TAG_VALUE>")
  time.sleep(0.05)
  span.finish()

init_tracer("<SERVICE_NAME>")
my_operation()

トレーサーが、その他の OpenTracing アプリケーションと同様に使用できるようになりました。OpenTracing Python の使用方法については opentracing.io を参照してください。

OpenTelemetry

OpenTelemetry のサポートは、opentelemetry-ext-datadog パッケージを使用してトレースを OpenTelemetry から Datadog にエクスポートすることで利用できます。

現在、この機能はベータ版です。期待どおりに機能しない場合は、サポートにお問い合わせください。

インストール

インストールするには

pip install opentelemetry-ext-datadog

使用方法

アプリケーションに Datadog プロセッサーとエクスポーターをインストールし、オプションを構成します。次に、OpenTelemetry インターフェイスを使用して、トレースおよびその他の情報を生成します。

from opentelemetry import trace
from opentelemetry.ext.datadog import (
    DatadogExportSpanProcessor,
    DatadogSpanExporter,
)
from opentelemetry.sdk.trace import TracerProvider

trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)

exporter = DatadogSpanExporter(
    agent_url="http://localhost:8126", service="example"
)

span_processor = DatadogExportSpanProcessor(exporter)
trace.get_tracer_provider().add_span_processor(span_processor)


with tracer.start_as_current_span("foo"):
    with tracer.start_as_current_span("bar"):
        with tracer.start_as_current_span("baz"):
            print("Hello world from OpenTelemetry Python!")

構成オプション

Datadog Agent の URL とスパンタグの値は、環境と Agent の場所次第で必要または希望に応じて構成できます。

Datadog Agent URL

デフォルトでは、OpenTelemetry Datadog Exporter はトレースを http://localhost:8126 に送信します。次の環境変数を構成して、トレースを別の URL に送信します。

  • DD_TRACE_AGENT_URL: Datadog Agent がトレースをリッスンする <host>:<port>。例: agent-host:8126

これらの値は、トレースエクスポーターレベルでオーバーライドできます。

exporter = DatadogSpanExporter(
    agent_url="http://dd-agent:8126", service="example"
)

タグ付け

次の環境変数を設定して、Datadog がエクスポートしたトレースに自動的にタグを付けるようにアプリケーションを構成します。

  • DD_ENV: アプリケーション環境。例: productionstaging
  • DD_SERVICE: アプリケーションのデフォルトのサービス名。例: billing-api
  • DD_VERSION: アプリケーションのバージョン。例: 2.52020031814151.3-alpha
  • DD_TAGS: カンマで区切られた値ペアのカスタムタグ。例: layer:api,team:intake
  • DD_ENVDD_SERVICE、または DD_VERSION が設定されている場合、DD_TAGS で定義されている対応する envservice、または version タグをオーバーライドします。
  • DD_ENVDD_SERVICEDD_VERSION が設定されて_いない_場合、DD_TAGS の対応するタグを使用して、環境、サービス、バージョンを構成できます。

タグ値は、トレースエクスポーターレベルでもオーバーライドできます。これにより、アプリケーションごとに値を設定できるため、同じホスト上の異なる環境について複数のアプリケーションレポートを作成できます。

exporter = DatadogSpanExporter(
    agent_url="http://dd-agent:8126",
    service="example",
    env='prod',
    version='1.5-alpha',
    tags='team:ops,region:west'
)

個々のスパンに直接設定できるタグは、アプリケーションレベルで定義された競合するタグに優先します。

OpenTelemetry リンク

その他の参考資料