Trace API（New Relicフォーマット）によるトレースの報告

独自のトレース実装を作成する場合は、 Trace APIを使用できます。このドキュメントでは、 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 に送信する方法について説明します。

1. データをレポートするアカウントのライセンスキーを取得します。

2. そのキーを以下の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'

   ヒント

   複数のPOSTを送信する場合は、 trace.idを一意の値に変更してください。同じtrace.idに対して同じペイロードまたはスパンidを複数回送信すると、UI で断片化されたトレースが発生する可能性があります。

3. テストがHTTP/1.1 202 Acceptedを返した場合は、UIに移動して、スパン属性service.name = Test Service Aを使用したテスト データのクエリを確認します。

   ヒント

   トレースは、トレースオブザーバーとトレースAPIの両方で処理されるため、最大で1分かかることがあります。

トレースAPIのペイロード（New Relicフォーマット）

Trace API JSON ペイロードはオブジェクトの配列であり、各オブジェクトは単一のトレースを表します。これらの各オブジェクトにはspansキーが必要で、 commonキーが含まれる場合もあります。spans (必須) にはオブジェクトの配列が含まれ、各オブジェクトはスパンを表します。common (オプション) 複数のスパンで情報を共有します。

spans配列の Span オブジェクト

上記の必要なキーのないリクエストは拒否され、 NrIntegrationErrorが生成されます。

commonオブジェクト (オプション)

おすすめの属性

必須ではありませんが、各スパンのattributesオブジェクトでデータを最大限に活用するには、これらの属性を含める必要があります。

予約属性

これらの属性は現在、New Relic の内部使用のために予約されています。明示的にブロックされているわけではありませんが、使用しないことをお勧めします。

その他の属性

制限された属性を除いて、 commonまたは各スパン オブジェクトのattributesオブジェクトに必要な任意の属性を追加できます。たとえば、 customer.idやuser.idなどの属性を追加して、トレース データの分析に役立てることができます。

newrelic形式を使用したトレース JSON の要件とガイドライン:

• 各JSONペイロードは、オブジェクトの配列です。
• 各オブジェクトには、必要なspansキーが含まれている必要があります。
• 各オブジェクトには、オプションのcommonキーを含めることができます。オブジェクト内の複数のスパンで情報を共有する場合は、これを使用します。
• スパン上のすべてのキーは、 commonブロック内の同じキーよりも優先されます。
• spansキーの値は、 spanオブジェクトのリストです。
• 一部の属性は必須であり、オプションのcommonブロックまたは各スパンに含める必要があります。
• 推奨属性およびカスタム属性は、オプションのcommonブロックおよび/または各スパン内のattributesという名前のキーの下にあるキーと値のペアのリストにオプションで含めることができます。

次の例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体験を提供します。例えば、データストアのスパンを表示させたり、エラーを表示させたりすることができます。
• 一般的な データの制限、必要なメタデータ、および応答の検証については、 を参照してください。
• トレースデータが表示されない場合は、 トラブルシューティング を参照してください。