独自のトレース実装を作成する場合は、 TraceAPIを使用できます。このドキュメントでは、 newrelic
形式とも呼ばれる一般的な形式でトレースを送信する方法について説明します。 (Zipkin 形式のデータを送信するには、 Zipkinを参照してください。)
スタートガイド
Trace API の使用方法はとても簡単です。
- 期待される形式(この場合は
newrelic
形式)でトレースデータを送信します。 - そのデータを適切な エンドポイントに送る 。
Trace API を使用する前に、Infinite Tracing を使用するかどうかを決定する必要があります。この点については、 Intro to Infinite Tracing および Sampling considerations をご覧ください。
Trace API の使用を開始するには、以下のいずれかの方法をとります。
- Infinite Tracing を使ってみませんか? Set up a trace observer の指示に従ってください。トレースオブザーバーを作成し、サンプルのペイロードをトレースオブザーバーのエンドポイントに送信する手順を説明しています。
- Infinite Tracing は不要ですか? サンプルペイロード を送信する方法をご覧ください(下記)。
サンプルトレースペイロードの送信(非 Infinite Tracing)
以下では、当社の newrelic
形式を使用して、標準的な(非Infinite Tracing )ペイロードを Trace API に送信する方法を説明します。
データをレポートするアカウントのライセンスキーを取得します。
そのキーを以下の JSON に挿入し、その JSON を私たちのエンドポイントに送信します。 注:EU の New Relic アカウントをお持ちの方は、代わりに EU のエンドポイント をご利用ください。
bash$curl -i -H 'Content-Type: application/json' \>-H 'Api-Key: YOUR_LICENSE_KEY' \>-H 'Data-Format: newrelic' \>-H 'Data-Format-Version: 1' \>-X POST \>-d '[${$"common": {$"attributes": {$"service.name": "Test Service A",$"host": "host123.example.com"$}$},$"spans": [${$"trace.id": "123456",$"id": "ABC",$"attributes": {$"duration.ms": 12.53,$"name": "/home"$}$},${$"trace.id": "123456",$"id": "DEF",$"attributes": {$"error.message": "Invalid credentials",$"service.name": "Test Service A",$"host": "host456.example.com",$"duration.ms": 2.97,$"name": "/auth",$"parent.id": "ABC"$}$}$]$}$]' 'https://trace-api.newrelic.com/trace/v1'テスト結果が
HTTP/1.1 202 Accepted
となった場合、 our UI で span 属性を使ったテストデータのクエリを見ることができます。service.name = Test Service A
.ヒント
トレースは、トレースオブザーバーとトレースAPIの両方で処理されるため、最大で1分かかることがあります。
トレース API のペイロード(New Relic フォーマット)
Trace API の JSON ペイロードは、オブジェクトの配列で、各オブジェクトは 1 つのトレースを表します。これらのオブジェクトは、それぞれ spans
キーを必要とし、 common
キーを含むこともあります。 spans
(必須) はオブジェクトの配列を含み、各オブジェクトはスパンを表します。 common
(オプション) は複数のスパン間で情報を共有します。
スパンのオブジェクト
の配列
フィールド | 種類 | 説明 | 必須 | デフォルト |
---|---|---|---|---|
| 文字列 | このスパンの一意の識別子。 | そう | 該当なし |
| 文字列 | 1つのトレース内のすべてのスパンで共有される一意の識別子。 | そう | 該当なし |
| ロング | ノー | UTCタイムゾーンでの現在時刻 | |
| オブジェクト |
| ノー | 該当なし |
上記の必須キーがないリクエストは拒否され、 NrIntegrationError
が生成されます。
共通の
オブジェクト(オプション)
フィールド | 種類 | 説明 | 必須 | デフォルト |
---|---|---|---|---|
| オブジェクト | ペイロード内のスパンに関する共通の詳細情報を追加する、キーと値のペアの任意のセットです。 | ノー | 該当なし |
おすすめの属性
必須ではありませんが、これらの属性は、各スパンの attributes
オブジェクトでデータを最適に使用するために含まれている必要があります。
属性 | デフォルト | 説明 |
---|---|---|
フロート | なし | スパンの長さをミリ秒単位で指定します。 |
文字列 | なし | このスパンの名前です。 |
文字列 | なし | このスパンの呼び出し元の ID。値は |
文字列 | なし | このスパンを作成したエンティティの名前。 |
予約属性
これらの属性は現在、New Relic の内部使用のために予約されています。明示的にブロックされているわけではありませんが、使用しないことをお勧めします。
属性 | デフォルト | 説明 |
---|---|---|
文字列 |
| これは、 |
entity.type string |
| エンティティタイプは、サービスを想定しています。 |
文字列 | なし |
|
その他の属性
attributes
オブジェクトには、 common
または各 span オブジェクトのいずれかに、必要な任意の属性を追加することができますが、 restricted attributes は例外です。例えば、 customer.id
や user.id
のような属性を追加して、トレースデータの分析に役立てることができます。
newrelic
フォーマットを使用したトレース JSON の要件とガイドライン。
- 各 JSON ペイロードは、オブジェクトの配列です。
- 各オブジェクトには、必要な
spans
キーが含まれている必要があります。 - 各オブジェクトには、オプションで
共通の
キーを含めることができます。オブジェクト内の複数のスパンで情報を共有したい場合に使用します。 - スパン上のどのキーも、
コモン
ブロックの同じキーよりも優先されます。 spans
キーの値は、span
オブジェクトのリストです。- 特定の属性は 必須 であり、オプションの
共通
ブロック、または各スパンのいずれかに含める必要があります。 - 推奨属性およびカスタム属性は、オプションとして、
attributes
というキーの下のキー・バリュー・ペアのリスト、オプションのcommon
ブロック、および/または、各スパンに含めることができます。
次の例では、 POST
、2 つのスパンがあり、どちらも trace.id 12345
とカスタム属性 host: host123.example.com
を持っています。最初のスパンには parent.id
がないため、これがトレースのルートとなります。2 番目のスパンの parent.id
は最初のスパンの ID を指しています。
[ { "common": { "attributes": { "host": "host123.example.com" } }, "spans": [ { "trace.id": "12345", "id": "abc", "timestamp": 1603336834823, "attributes": { "user.email": "bob@newr.com", "service.name": "my-service", "duration.ms": 750, "name": "my-span" } }, { "trace.id": "12345", "id": "def", "timestamp": 1603336834899, "attributes": { "parent.id": "abc", "service.name": "second-service", "duration.ms": 750, "name": "second-span" } } ] }]
New Relic でのスパンの表示方法を制御する方法 (エラーの追加やスパンをデータストアのスパンとして設定するなど) については、 スパンの装飾 を参照してください。
分散型トレーシングについてはこちらをご覧ください。
- Trace API のデータが UI のどこに表示されるかについて.
- スパンを装飾する方法をご紹介します よりリッチで詳細な UI 体験を提供します。例えば、データストアのスパンを表示させたり、エラーを表示させたりすることができます。
- 一般的な データの制限、必要なメタデータ、および応答の検証については、 を参照してください。
- トレースデータが表示されない場合は、 トラブルシューティング を参照してください。