PHP Custom Instrumentation using the OpenTelemetry API

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

概要

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

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

セットアップ

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