トレースAPIに関する情報 データの要件を含みます。
- データの仕様と上限値
- 必要なメタデータ（ヘッダ、クエリパラメータ）
- レスポンスバリデーションの詳細
このドキュメントは、Trace API 全体に適用されます。特定のデータフォーマットに関するルールについては
エンドポイント
すべてのトレースデータは、HTTPS POST で Trace API エンドポイントに送信されます。お客様のセットアップに応じて、いくつかのエンドポイントを用意しています。
- デフォルトのトレースAPIエンドポイント：
https://trace-api.newrelic.com/trace/v1 - EUデータセンター：
https://trace-api.eu.newrelic.com/trace/v1（他のEUエンドポイントを参照）。 - Infinite Tracing : Trace オブザーバーのセットアップを完了すると、エンドポイントとして使用するカスタム YOUR_TRACE_OBSERVER_URL 値を取得します。Trace API を使用する統合 (たとえば、 Kamon レポーター) を使用している場合は、そのエンドポイントとの統合を構成する必要があります。また、トレース サービスのサンプリングを調整して、スパンの 100% を送信することもできます。
- FedRAMP: FedRAMP エンドポイントを参照してください。
データフォーマット
現在、Trace APIは2種類のデータ形式を受け付けています。
zipkin：Zipkinトレースデータのレポート用。 ZipkinデータはZipkinJSONv2である必要があります。newrelic：他のすべてのトレースデータを報告するため。
制限された属性
以下の表の属性は、 newrelic形式のJSON（ attributesブロック内）およびzipkin形式のJSON（ tagsブロック内）で制限されています。これらのキーを持つ値はすべて省略されます：
制限付き属性 | 説明 |
|---|---|
ストリング | このスパンを作成したエンティティの一意の識別子。可能な場合は、 |
ストリング | APMエージェントからのデータとの下位互換性のために使用されます。 |
以下の表の属性は、エンティティを識別するために内部的に使用されます。メトリック・データ・ポイントの属性セクションでこれらのキーを使用して送信された値は、UIにエンティティが表示されなかったり、遠隔測定が期待したエンティティに関連付けられないなど、未定義の動作を引き起こす可能性があります。詳細については、 Entity synthesis を参照してください。
制限付き属性 | description |
|---|---|
ストリング | このスパンに関連するエンティティの一意の識別子。 |
ストリング | エンティティの人間が読める名前で、UIでエンティティを識別するためによく使われます。 |
ストリング | ホストやアプリケーションなど、異なるタイプのエンティティを区別するために使用されます。 |
リクエストのメタデータ（ヘッダ、クエリパラメータ）
次の表は、すべてのトレースデータ形式に必要なリクエストメタデータを示しています。このメタデータは、インジェストリクエストのHTTPヘッダとして送信することもできますし、場合によってはクエリパラメータとして提供することもできます。これは、ヘッダの修正ができないトレースフレームワークでは必要になるかもしれません。
重要
セキュリティ上の注意：クエリパラメータはURL内に存在し、暗号化されてNew Relicに受信される前にログに記録される可能性があるため、ヘッダーの使用をお勧めします。クエリーパラメーターとして送られるデータはすべて、URLセーフでなければなりません。
ヘッダー | クエリのパラメータ？ | 詳細 |
|---|---|---|
| いいえ | 必須。 |
| いいえ | 必須です。 リクエストボディの長さをオクテット(8ビットバイト)で表したもの。このヘッダーは、通常、データを送信する基礎となるHTTPクライアントによってデフォルトで設定されており、ほとんどの場合、エンドユーザーが追加の努力をする必要はありません。 |
| はい（大文字と小文字を区別します） | 必要です。 Trace APIには、 ライセンスキー が必要です。これがヘッダーとクエリーパラメーターの両方で提供されている場合は、値が一致している必要があります。 |
| いいえ | ペイロードを圧縮する場合に必要です。値は |
| はい |
存在する場合、 |
| はい |
存在する場合、 これらの値の組み合わせは2通りしかありません。
|
| いいえ | オプション-将来の使用のために予約されています。値は有効な |
レスポンス・バリデーション
トレースデータを正常に送信するための応答には、 requestIdが含まれます。例えば：
{ "requestId": "c1bb62fc-001a-b000-0000-016bb152e1bb" }成功/エラーの通知方法は2種類あります。
HTTPステータスコード （同期）。認証やリクエストのエラーは、HTTPステータスコードで通知されます。
NrIntegrationErrorイベント（非同期）。 JSONペイロードのエラーまたはその他のセマンティックエラーは、ライセンスキーがリクエストに関連付けられているアカウントに保存されているNrIntegrationErrorイベントを介して非同期的に通知されます。このタイプのすべてのエラーの場合、属性newRelicFeatureはDistributed Tracingになり、requestIdはエンドポイント応答からのrequestIdになります。
202応答を受信し、 NrIntegrationErrorイベントが表示されない場合、データは約1分でグローバル分散トレースUIに表示されます。次のような標準のトレース検索を使用して、トレースを見つけることができるはずです。
traceId = TRACE_ID_SENTデータ制限
トレース関連の制限については、分散トレースのしくみを参照してください。