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 にデータが表示されていることを確認するために行うことができます。

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

(オプション、無限トレースを有効にするため) まず、トレースオブザーバーを設定する必要があります。この手順には、一般的な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でした。( traceIdではなく) trace.idの変換された属性によって検索することに注意してください。

Distributed Tracing Zipkin Integration Searching for sample trace

詳細について：

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およびその他のメタデータの説明については、リクエストメタデータを参照してください。

Zipkinデータの変換

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

ジプキンタグ	New Relicには...として保存されています。	詳細
`traceId`	`trace.id`	トレースのユニークな識別子。
`id`	`id`	スパンの一意の識別子。
`parentId`	`parent.id`	サービスを呼び出した上流のスパンの識別子。
`kind`	`kind`	`Client`または`Server`のいずれか。
`name`	`name`	スパンの名前。
`duration`	`duration.ms`	Zipkin v2 のスパンは、マイクロ秒で指定された持続時間を持たなければならず、ミリ秒に変換されます。
ローカルエンドポイント: `serviceName`	`service.name`	Zipkin v2 サービス名を使用して、このスパンを作成したエンティティを識別します。値または空の文字列が指定されていない場合、スパンは「UNKNOWN」エンティティに割り当てられ、UI にそのように表示されます。UI で完全なエクスペリエンスを得るには、この値を指定する必要があります。
ローカルエンドポイント: `port`	`localEndpoint.port`	`localEndpoint`オブジェクトのすべての値は、呼ばれるスパン属性にフラット化されます `localEndpoint.key`
`tags`	属性として報告	Zipkin v2 の`tags`オブジェクトのキーと値のペアは、スパン属性として書き込まれます。
アノテーション	対応していません	現在、トレースAPIではアノテーションをサポートしていません。スパンにアノテーションが含まれていても拒否されることはありませんが、アノテーションのデータは書き込まれません。

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

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

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