トレース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
ブロック内)で制限されています。これらのキーを持つ値はすべて省略されます:
制限付き属性 | 説明 |
---|---|
ストリング | このスパンを作成したエンティティの一意の識別子。可能な場合は、 |
ストリング | からのデータとの後方互換性のために使用されます。 エージェント。 |
以下の表の属性は、エンティティを識別するために内部的に使用されます。メトリック・データ・ポイントの属性セクションでこれらのキーを使用して送信された値は、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
データ制限
トレース関連の制限については、分散トレースのしくみを参照してください。