• ログイン無料アカウント

本書は、お客様のご参考のために原文の英語版を機械翻訳したものです。

英語版と齟齬がある場合、英語版の定めが優先するものとします。より詳しい情報については、本リンクをご参照ください。

問題を作成する

トレースAPIの一般的な要件と制限

トレースAPIに関する情報 データの要件を含みます。

  • データの仕様と上限値
  • 必要なメタデータ(ヘッダ、クエリパラメータ)
  • レスポンスバリデーションの詳細

このドキュメントは、Trace API 全体に適用されます。特定のデータフォーマットに関するルールについては

エンドポイント

すべてのトレースデータは、HTTPS POST で Trace API エンドポイントに送信されます。お客様のセットアップに応じて、いくつかのエンドポイントを用意しています。

データフォーマット

現在、Trace APIは2種類のデータ形式を受け付けています。

  • zipkin : Zipkin のトレースデータを報告するためのものです。Zipkin データは Zipkin JSON v2 である必要があります。
  • newrelic : その他のすべてのトレースデータを報告するためのものです。

制限された属性

下の表の属性は、 newrelic-format JSON (in the attributes block) と zipkin -format JSON (in the tags block) で制限されています。 これらのキーを持つすべての値は省略されます。

制限付き属性

説明

entityGuid

文字列

このスパンを作成したエンティティの一意の識別子。 service.name から生成されます(利用可能な場合)。

guid

文字列

APMエージェントからのデータとの下位互換性のために使用されます。

以下の表の属性は、エンティティを識別するために内部的に使用されます。メトリック・データ・ポイントの属性セクションでこれらのキーを使用して送信された値は、UIにエンティティが表示されなかったり、遠隔測定が期待したエンティティに関連付けられないなど、未定義の動作を引き起こす可能性があります。詳細については、 Entity synthesis を参照してください。

制限付き属性

説明

entity.guid

文字列

このスパンに関連するエンティティの一意の識別子。

entity.name

文字列

エンティティの人間が読める名前で、UIでエンティティを識別するためによく使われます。

entity.type

文字列

ホストやアプリケーションなど、異なるタイプのエンティティを区別するために使用されます。

リクエストのメタデータ(ヘッダ、クエリパラメータ)

次の表は、すべてのトレースデータ形式に必要なリクエストメタデータを示しています。このメタデータは、インジェストリクエストのHTTPヘッダとして送信することもできますし、場合によってはクエリパラメータとして提供することもできます。これは、ヘッダの修正ができないトレースフレームワークでは必要になるかもしれません。

重要

セキュリティ上の注意:クエリパラメータはURL内に存在し、暗号化されてNew Relicに受信される前にログに記録される可能性があるため、ヘッダーの使用をお勧めします。クエリーパラメーターとして送られるデータはすべて、URLセーフでなければなりません。

ヘッダー

クエリのパラメータ?

詳細

コンテンツタイプ

いいえ

必須です。 Must be application/json.

Content-Length

いいえ

必須です。 リクエストボディの長さをオクテット(8ビットバイト)で表したもの。このヘッダーは、通常、データを送信する基礎となるHTTPクライアントによってデフォルトで設定されており、ほとんどの場合、エンドユーザーが追加の努力をする必要はありません。

Api-Key

はい(大文字と小文字を区別します)

必要です。 Trace APIには、 ライセンスキー が必要です。これがヘッダーとクエリーパラメーターの両方で提供されている場合は、値が一致している必要があります。

Content-Encoding

いいえ

圧縮されたペイロードの場合は必要です。 値は gzip でなければなりません。

データ形式

はい

Required for zipkin .Optional for newrelic.

存在する場合、 Data-Format-Version も存在しなければなりません。

データ-フォーマット-バージョン

はい

に必要です。 zipkin .

存在する場合は、 Data-Format も存在する必要があります。

これらの値の組み合わせは2通りしかありません。

  • Data-Formatzipkin である場合、 Data-Format-Version2 でなければなりません。
  • Data-Formatnewrelic である場合、 Data-Format-Version1 でなければなりません。

x-request-id

いいえ

Optional - Reserved for future use. The value must be a valid UUID4.この値は、各リクエストに対して一意であることが期待されます。

レスポンス・バリデーション

トレースデータの送信に成功した場合のレスポンスには、 requestId が含まれます。例えば、以下のようになります。

{"requestId":"c1bb62fc-001a-b000-0000-016bb152e1bb"}

成功/エラーの通知方法は2種類あります。

  • HTTPステータスコード (同期)。認証やリクエストのエラーは、HTTPステータスコードで通知されます。

  • NrIntegrationError events (asynchronous)。JSONペイロードのエラーやその他のセマンティックエラーは、 NrIntegrationError イベント を通じて非同期的にシグナルが送られます。このイベントは、 ライセンスキー がリクエストに関連付けられているアカウントに保存されます。このタイプのすべてのエラーについて、属性 newRelicFeatureDistributed Tracing となり、 requestId はエンドポイント応答の requestId となります。

202 レスポンスを受信し、 NrIntegrationError イベントが表示されなければ、約1分でNew Relic Oneのグローバルな 分散型トレースUI にデータが表示されるはずです。標準的な トレース検索 のような方法でトレースを見つけることができるはずです。

traceId = TRACE_ID_SENT

データ制限

トレース関連の制限については、 How distributed tracing works を参照してください。

Copyright © 2022 New Relic Inc.