OpenTelemetry API を使用した PHP カスタム インスツルメンテーション

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. OpenTelemetry API パッケージをインストールします。
composer require open-telemetry/sdk

  1. OpenTelemetry PHP Manual Instrumentation ドキュメントに従って、ご希望の手動 OpenTelemetry インスツルメンテーションを PHP コードに追加します。

  2. Datadog PHP トレーシングライブラリ をインストールします。

  3. DD_TRACE_OTEL_ENABLED を true に設定します。

Datadog は、これらの OpenTelemetry スパンと他の Datadog APM スパンを組み合わせて、アプリケーションの単一のトレースにします。

スパンタグの追加

スパンを開始する瞬間に属性を追加できます。

$span = $tracer->spanBuilder('mySpan')
    ->setAttribute('key', 'value')
    ->startSpan();

またはスパンがアクティブな間:

$activeSpan = OpenTelemetry\API\Trace\Span::getCurrent();

$activeSpan->setAttribute('key', 'value');

スパンにエラーを設定する

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

// スパンを作成
$span = $tracer->spanBuilder('mySpan')->startSpan();

throw new \Exception('Oops!');

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

トレースにエラーフラグを付けることは、手動でも可能です。

use OpenTelemetry\API\Trace\Span;
use OpenTelemetry\Context\Context;

// トレーサーの初期化など、セットアップ手順の後にのみ実行できます。

try {
    throw new \Exception('Oops!');
} catch (\Exception $e) {
    $rootSpan = Span::fromContext(Context::getRoot());
    $rootSpan->recordException($e);
}

タグの追加

スパンを追加するには

// トレーサーを入手するか、既存のものを使用
$tracerProvider = \OpenTelemetry\API\Globals::tracerProvider();
$tracer = $tracerProvider->getTracer('datadog')

// スパンを作成
$span = $tracer->spanBuilder('mySpan')->startSpan();

// ... 処理内容

// スパンを閉じる
$span->end();

スパン イベントの追加

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

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

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

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

$span->addEvent("Event With No Attributes");
$span->addEvent(
    "Event With Some Attributes", 
    [ 
        'int_val' => 1, 
        'string_val' => "two", 
        'int_array' => [3, 4], 
        'string_array' => ["5", "6"],
        'bool_array' => [true, false]
    ]
);

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

例外の記録

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

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

$span->recordException(new \Exception("Error Message"));
$span->recordException(new \Exception("Error Message"), [ "status" => "failed" ]);

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

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

現在アクティブなスパンにアクセスするには

$span = OpenTelemetry\API\Trace\Span::getCurrent();

その他の参考資料

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

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