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

独自のトレース実装を作成したい場合は、 Trace API をご利用ください。このドキュメントでは、一般的なフォーマットである new-relic フォーマットでトレースを送信する方法を説明しています。(Zipkin 形式のデータを送信するには、 Zipkin を参照してください。)

スタートガイド

Trace APIの使用方法はとても簡単です。

トレースデータを期待されるフォーマットで送信すること（この場合、当社の new-relic のフォーマット）。
そのデータを適切なエンドポイントに送る。

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 に送信する方法を説明します。

データをレポートするアカウントのライセンスキーを取得します。
そのキーを以下のJSONに挿入し、そのJSONを私たちのエンドポイントに送信します。注：EUのNew Relicアカウントをお持ちの方は、代わりにEUのエンドポイントをご利用ください。
```
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 をユニークな値に変更してください。同じペイロードやスパン id を、同じ trace.id に対して複数回送信すると、UI でのトレースが断片的になることがあります。
テスト結果が HTTP/1.1 202 Accepted となった場合、 our UI で span 属性を使ったテストデータのクエリを見ることができます。 service.name = Test Service A.
ヒント
トレースは、トレースオブザーバーとトレースAPIの両方で処理されるため、最大で1分かかることがあります。

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

Trace API の JSON ペイロードは、オブジェクトの配列で、各オブジェクトは 1 つのトレースを表します。これらのオブジェクトは、それぞれ spans キーを必要とし、 common キーを含むこともあります。 spans (必須) はオブジェクトの配列を含み、各オブジェクトはスパンを表します。 common (オプション) は複数のスパン間で情報を共有します。

`スパンのオブジェクト` の配列

フィールド	種類	説明	必須	デフォルト
`id`	文字列	このスパンの一意の識別子。	そう	該当なし
`trace.id`	文字列	1つのトレース内のすべてのスパンで共有される一意の識別子。	そう	該当なし
`タイムスタンプ`	ロング	スパンの開始時間をUnixエポックからのミリ秒単位で表示.	ノー	UTCタイムゾーンでの現在時刻
`属性`	オブジェクト	`duration.ms`, `name`, `parent.id` を追加することを強く推奨します。	ノー	該当なし

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

`共通の` オブジェクト（オプション）

フィールド	種類	説明	必須	デフォルト
`属性`	オブジェクト	ペイロード内のスパンに関する共通の詳細情報を追加する、キーと値のペアの任意のセットです。 `duration.ms` , `name` , `parent.id` を追加することを強く推奨します。	ノー	該当なし

属性	デフォルト	説明
`duration.ms` フロート	なし	スパンの長さをミリ秒単位で指定します。
`name` 文字列	なし	このスパンの名前です。
`parent.id` 文字列	なし	このスパンの呼び出し元の ID。値は `null` これがルートスパンの場合。ルート・スパンのないトレースは表示されません。
`service.name` 文字列	なし	このスパンを作成したエンティティの名前。

予約属性

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

属性	デフォルト	説明
`entity.name` 文字列	`service.name`	これは、 `service.name` 属性から派生したものです。
entity.type string	`サービス`	エンティティタイプは、サービスを想定しています。
`entity.guid` 文字列	なし	`entity.guid` は、New Relic のバックエンドでエンティティを一意に識別する派生値です。

属性

デフォルト

説明

entity.name

文字列

service.name

これは、 service.name 属性から派生したものです。

entity.type
string

サービス

エンティティタイプは、サービスを想定しています。

entity.guid

文字列

なし

entity.guid は、New Relic のバックエンドでエンティティを一意に識別する派生値です。

その他の属性

attributes オブジェクトには、 common または各 span オブジェクトのいずれかに、必要な任意の属性を追加することができますが、 restricted attributes は例外です。例えば、 customer.id や user.id のような属性を追加して、トレースデータの分析に役立てることができます。

newrelic フォーマットを使用したトレースJSONの要件とガイドライン。

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

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

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

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

スタートガイド

サンプルトレースペイロードの送信（非Infinite Tracing）

ヒント

ヒント

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

`スパンのオブジェクト` の配列

`共通の` オブジェクト（オプション）

おすすめの属性

予約属性

その他の属性

分散型トレーシングについてはこちらをご覧ください。

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

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

スタートガイド

サンプルトレースペイロードの送信（非Infinite Tracing）

ヒント

ヒント

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

スパンのオブジェクト の配列

共通の オブジェクト（オプション）

おすすめの属性

予約属性

その他の属性

分散型トレーシングについてはこちらをご覧ください。

`スパンのオブジェクト` の配列

`共通の` オブジェクト（オプション）