API で Agent にトレースを送信する

Datadog の APM を使用すると、コードをトレースしてパフォーマンスメトリクスを収集し、アプリケーションのどの部分が実行に時間がかかるか、あるいは非効率であるかを特定できます。

トレーシングデータは、インスツルメントされたコードから HTTP API を介して Datadog Agent に送信されます。Datadog トレーシングライブラリを使用することで、Datadog Agent へのメトリクスの送信を簡略化できます。ただし、それらのライブラリを使用できないアプリケーションや、公式の Datadog トレーシングライブラリがまだ提供されていない言語で書かれたアプリケーションをインスツルメントするために、API を直接使用することもできます。

トレーシング API は、サービス側の API というよりはむしろ Agent の API です。トレースをローカルエンドポイント http://localhost:8126/v0.3/traces に送信して、それを Agent が Datadog に転送できるようにします。

パス

PUT http://localhost:8126/v0.3/traces

リクエスト

トレースは、次のようなトレースの配列として送信されます。

[ trace1, trace2, trace3 ]

それぞれのトレースは、次のようなスパンの配列となります。

trace1 = [ span, span2, span3 ]

各スパンは trace_id、span_id、resource などを持つ辞書として機能します。トレース内の各スパンは同じ trace_id を使用する必要がありますが、trace_id と span_id は異なる値でなければなりません。

モデル

Datadog トレーシングライブラリは、64 ビットおよび 128 ビットのトレースを両方サポートしています。詳しくは、トレースとスパン ID のフォーマットをご覧ください。
フィールドタイプ説明
durationint64リクエストの処理時間 (ナノ秒単位)。
errorint32エラーが発生したことを示すには、この値を 1 に設定します。エラーが発生した場合は、エラーメッセージ、タイプ、スタックなどの追加情報を meta プロパティで渡す必要があります。
metaオブジェクトキー/値メタデータのセット。キーと値は文字列でなければなりません。
- <any-key>文字列キー値メタデータの追加のプロパティ。
モニターオブジェクトキー/値メタデータのセット。キーは文字列、値は 64 ビット浮動小数点数でなければなりません。
- <any-key>doubleキー値メトリクスの追加のプロパティ。
name文字列スパン名。スパン名の長さは、最大 100 文字です。
parent_idint64親スパンの整数ID。
resource文字列トレース対象のリソース。リソース名の長さは、最大 5000 文字です。
service文字列トレース対象のサービス。サービス名の長さは、最大 100 文字です。
span_idint64スパンの整数 (64 ビット符号なし) ID。
startint64リクエストの開始時間を UNIX Epoch からのナノ秒で指定します。
trace_idint64 または int128このスパンが含まれるトレースの一意の整数 (64 ビット符号なし、または 128 ビット符号なし) ID。
typeenumリクエストの種類。web、db、cache、custom などの enum 値を許容します。

例

[
  [
    {
      "duration": 12345,
      "error": "integer",
      "meta": {
        "<any-key>": "string"
      },
      "metrics": {
        "<any-key>": "number"
      },
      "name": "span_name",
      "parent_id": "integer",
      "resource": "/home",
      "service": "service_name",
      "span_id": 987654321,
      "start": 0,
      "trace_id": 123456789,
      "type": "web"
    }
  ]
]

応答

200
OK

例

    # Curl コマンド
curl -X PUT "http://localhost:8126/v0.3/traces" \
-H "Content-Type: application/json" \
-d @- << EOF
[
  [
    {
      "duration": 12345,
      "name": "span_name",
      "resource": "/home",
      "service": "service_name",
      "span_id": 987654321,
      "start": 0,
      "trace_id": 123456789
    }
  ]
]
EOF
    # Invoke-RestMethod コマンド

$uri = "http://localhost:8126/v0.3/traces"
$headers = @{
    "Content-Type" = "application/json"
}
$body = @"
[
  [
    {
      "duration": 12345,
      "name": "span_name",
      "resource": "/home",
      "service": "service_name",
      "span_id": 987654321,
      "start": 0,
      "trace_id": 123456789
    }
  ]
]
"@

Invoke-RestMethod -Uri $uri -Method Put -Body $body -Headers $headers

    その他の参考資料

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

    Datadog の APM トレーシングについてドキュメント more more APM の用語と概要ドキュメント more more