トレース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ブロック内) で制限されています。 Any values with these keys will be omitted :
制限付き属性 | 説明 |
|---|---|
ストリング | このスパンを作成したエンティティの一意の識別子。可能な場合は、 |
ストリング | エージェントのデータとの下位互換性のために使用されます。 |
以下の表の属性は、エンティティを識別するために内部的に使用されます。メトリック・データ・ポイントの属性セクションでこれらのキーを使用して送信された値は、UIにエンティティが表示されなかったり、遠隔測定が期待したエンティティに関連付けられないなど、未定義の動作を引き起こす可能性があります。詳細については、 Entity synthesis を参照してください。
制限付き属性 | description |
|---|---|
ストリング | このスパンに関連するエンティティの一意の識別子。 |
ストリング | エンティティの人間が読める名前で、UIでエンティティを識別するためによく使われます。 |
ストリング | ホストやアプリケーションなど、異なるタイプのエンティティを区別するために使用されます。 |
リクエストのメタデータ（ヘッダ、クエリパラメータ）
次の表は、すべてのトレースデータ形式に必要なリクエストメタデータを示しています。このメタデータは、インジェストリクエストのHTTPヘッダとして送信することもできますし、場合によってはクエリパラメータとして提供することもできます。これは、ヘッダの修正ができないトレースフレームワークでは必要になるかもしれません。
重要
セキュリティ上の注意：クエリパラメータはURL内に存在し、暗号化されてNew Relicに受信される前にログに記録される可能性があるため、ヘッダーの使用をお勧めします。クエリーパラメーターとして送られるデータはすべて、URLセーフでなければなりません。
ヘッダー | クエリのパラメータ？ | 詳細 |
|---|---|---|
| いいえ | Required. |
| いいえ | Required. チャンクエンコーディングで送信されない限り、リクエスト本体の長さ（オクテット（8 ビットバイト）単位）。 このヘッダーは通常、データを送信する基盤となる HTTP クライアントによってデフォルトで設定され、ほとんどの場合、エンドユーザーによる追加の作業は必要ありません。 |
| はい（大文字と小文字を区別します） | Required. APIには が必要です。 これがヘッダーとクエリ ヘッダーの両方として指定されている場合、値は一致する必要があります。 |
| いいえ | Required if compressed payload. 値は |
| はい | Required for 存在する場合、 |
| はい | Required for 存在する場合、 これらの値の組み合わせは2通りしかありません。
|
| いいえ | Optional - Reserved for future use. 値は有効な |
レスポンス・バリデーション
トレースデータを正常に送信するための応答には、 requestIdが含まれます。例えば：
{ "requestId": "c1bb62fc-001a-b000-0000-016bb152e1bb" }成功/エラーの通知方法は2種類あります。
HTTP status code （同期）。 認証およびリクエスト エラーは、HTTP ステータス コードを介して通知されます。
NrIntegrationErrorイベント（非同期）。 JSON ペイロードのエラーまたはその他のセマンティック エラーは、リクエストに関連付けられているを持つアカウントに保存されているNrIntegrationErrorイベントを介して非同期的に通知されます。 このタイプのすべてのエラーの場合、属性newRelicFeatureはDistributed Tracingになり、requestIdエンドポイント応答のrequestIdになります。
202応答を受信し、 NrIntegrationErrorイベントが表示されない場合、データは約1分でグローバル分散トレースUIに表示されます。次のような標準のトレース検索を使用して、トレースを見つけることができるはずです。
traceId = TRACE_ID_SENTデータ制限
トレース関連の制限については、分散トレースのしくみを参照してください。