Trace API を通じて Zipkin フォーマットのトレースを報告する。

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

Zipkin バージョン要件

Trace API は、 Zipkin JSON v2（またはそれ以上）からのデータを修正なしでサポートします。このバージョンの詳細については、 Zipkin v2 release details および Zipkin v2 schema を参照してください。

トレースAPI利用の概要

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

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

当社のsend-data命令には、Infinite Tracingを有効にするオプションがあります。これについては、 Intro to Infinite Tracing および Sampling considerations を参照してください。

トレースAPIの使用を開始するには、オプションを選択します。

Send a sample trace: New Relic にトレースを送信する curl の例を示しています。トレース API の仕組みを理解したり、New Relic にデータが表示されていることを確認したりするのに便利です。
既存のZipkinインストルメントからのデータを報告する: 既存のZipkinインストルメントがある場合は、データを送信するエンドポイントを変更するだけでOKです。

Zipkin トレースペイロードのサンプルを送信

このセクションでは、シンプルな Zipkin フォーマットのトレースを curl リクエストで Trace API に送信する方法を説明します。この方法は、API がどのように動作するかを学び、詳細なインスツルメンテーションを行う前に New Relic にデータが表示されていることを確認するために行うことができます。

サンプルペイロードの送信を開始するには

(Optional, to enable Infinite Tracing) まず、トレースオブザーバーを設定する必要があります。この手順には、一般的な new-relic 形式のサンプルトレースを送信する手順が含まれています。この手順に進んだら、代わりに Zipkin 形式のトレースを送信する方法を学ぶためにここに戻ってください。
以下の手順でZipkinフォーマットのペイロードを送信してください。

Zipkinフォーマットのペイロードを送信

Zipkin形式のサンプルトレースを送信する場合。

データを報告したいアカウントのライセンスキーを取得します。

以下、curlリクエストを実行することになります。その際の注意事項です。

ライセンスキーのプレースホルダーをライセンスキーに置き換えます。
Infinite Tracingを使用している場合は、標準のエンドポイントの代わりに、
YOUR_TRACE_OBSERVER_URL
の値を使用してください。
複数のポストを送信したい場合は、トレースIDを別の値に変更してください。同じペイロードやスパン ID を、同じ traceId に対して複数回送信すると、UI上でトレースが断片的になることがあります。

bash

$curl -i -H 'Content-Type: application/json' \
>    -H 'Api-Key: NEW_RELIC_API_KEY' \
>    -H 'Data-Format: zipkin' \
>    -H 'Data-Format-Version: 2' \
>    -X POST \
>    -d '[
$        {
$            "traceId": "test-zipkin-trace-id-1",
$            "id": "3e0f5885710776cd",
$            "kind": "CLIENT",
$            "name": "post",
$            "duration": 508068,
$            "localEndpoint": {
$                "serviceName": "service-1",
$                "ipv4": "127.0.0.1",
$                "port": 8080
$            },
$            "tags": {
$            }
$        },
$        {
$            "traceId": "test-zipkin-trace-id-1",
$            "parentId": "3e0f5885710776cd",
$            "id": "asdf9asdn123lkasdf",
$            "kind": "CLIENT",
$            "name": "service 2 span",
$            "duration": 2019,
$            "localEndpoint": {
$                "serviceName": "service-2",
$                "ipv4": "127.0.0.1",
$                "port": 8080
$            },
$            "tags": {
$                "error.message": "Invalid credentials"
$            }
$        }
$    ]' 'https://trace-api.newrelic.com/trace/v1'

1 分以内に、トレースは私たちの分散型トレース UI で利用できるはずです。それを見つけるには、 trace.id のクエリを実行してください。この例では、 test-zipkin-trace-id-1 でした。 transformed attribute of trace.id (not traceId)で検索することに注意してください。

詳細について：

Trace API のデータが UI のどこに表示されるかについて.
既存のZipkinインストルメントからデータを送信する.
タグを追加してスパンを装飾する方法について説明します。これにより、トレースのUIでの表示方法をカスタマイズすることができ、より豊かで便利な体験ができるようになります。
エンドポイントの一般的な情報（データの制限、必要なメタデータ、および応答の検証）について学びます。
Zipkinのデータがどのように変換され、私たちのフォーマットに保存されているのかをご紹介します。
トレースデータが表示されない場合は、トラブルシューティングを参照してください。

既存のZipkinインストルメントからデータを送信

予備知識です。

Infinite Tracing を有効にしたい場合は、まずトレースオブザーバーをセットアップする必要があります。
最初にサンプルペイロードを送信して、正常に動作しているかどうかを確認することが有効です。

既存のZipkinインスツルメンテーションからのデータをレポートするには、Zipkinトレーサーに適切なトレースAPIエンドポイントに必要なリクエストメタデータを指定します。必要なメタデータは、ヘッダまたはクエリパラメータとして送ることができます（Zipkin トレーサーのバージョンによっては、HTTP ヘッダを指定できないものもあります）。

以下は、Trace API 用に設定された Java で Zipkin OkHttpSender を作成する場合の例です。

OkHttpSender.create("https://trace-api.newrelic.com/trace/v1?Api-Key=NEW_RELIC_LICENSE_KEY&Data-Format=zipkin&Data-Format-Version=2");

なお、Infinite Tracingを使用している場合や、EU地域のNew Relicアカウントを持っている場合は、エンドポイントが異なります。

Api-Key やその他のメタデータの説明については、 Request metadata を参照してください。

Zipkinデータの変換

一貫性のある検索/クエリエクスペリエンスを実現するために、一部のZipkinデータはNew Relic 属性のネーミングに合わせて変換されます。トレースデータの保存方法や構造については、 How distributed tracing works をご覧ください。

ジプキンタグ	New Relicには...として保存されています。	詳細
traceId	trace.id	トレースのユニークな識別子。
`id`	`id`	スパンの一意の識別子。
parentId	parent.id	サービスを呼び出した上流のスパンの識別子。
`種類`	`種類`	Either `Client` or `Server`.
`name`	`name`	スパンの名前。
`デュレーション`	`duration.ms`	Zipkin v2 のスパンは、マイクロ秒で指定された持続時間を持たなければならず、ミリ秒に変換されます。
localEndpoint: `serviceName`	`service.name`	このスパンを作成したエンティティを識別するために、Zipkin v2のサービス名を使用しています。
localEndpoint: `ポート`	`localEndpoint.port`	`localEndpoint` オブジェクトのすべての値は、 `localEndpoint.key という span 属性にフラット化されます。`
`タグ`	属性として報告	Zipkin v2 の `タグ` オブジェクトの Key:Value ペアは、span 属性として記述されます。
アノテーション	対応していません	現在、トレースAPIではアノテーションをサポートしていません。スパンにアノテーションが含まれていても拒否されることはありませんが、アノテーションのデータは書き込まれません。

その他のタグ/属性の追加

tags ブロックには、 restricted tags を除いて、好きなタグを追加することができます。たとえば、 customer.id や user.id などの属性を追加して、トレースデータの分析に役立てたい場合があります。タグは New Relic の属性に変換されます。

New Relic でのスパンの表示方法を制御する方法 (エラーの追加やスパンをデータストアのスパンとして設定するなど) については、スパンの装飾を参照してください。