• ログイン

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

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

問題を作成する

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

独自のトレース実装を作成する場合は、 TraceAPIを使用できます。このドキュメントでは、 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'
  3. テスト結果が 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を追加することを強くお勧めします。

ノー

該当なし

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

属性

デフォルト

説明

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 のバックエンドでエンティティを一意に識別する派生値です。

その他の属性

attributes オブジェクトには、 common または各 span オブジェクトのいずれかに、必要な任意の属性を追加することができますが、 restricted attributes は例外です。例えば、 customer.iduser.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 でのスパンの表示方法を制御する方法 (エラーの追加やスパンをデータストアのスパンとして設定するなど) については、 スパンの装飾 を参照してください。

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

Copyright © 2022 New Relic株式会社。

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