• ログイン

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

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

問題を作成する

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

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

  1. (Optional, to enable Infinite Tracing) まず、 トレースオブザーバーを設定する必要があります 。この手順には、一般的な new-relic 形式のサンプルトレースを送信する手順が含まれています。この手順に進んだら、代わりに Zipkin 形式のトレースを送信する方法を学ぶためにここに戻ってください。
  2. 以下の手順で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)で検索することに注意してください。

詳細について:

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

予備知識です。

既存の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.iduser.id などの属性を追加して、トレースデータの分析に役立てたい場合があります。タグは New Relic の 属性 に変換されます。

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

Copyright © 2022 New Relic株式会社。

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.