• ログイン今すぐ開始

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

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

問題を作成する

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

独自のトレース実装を作成する場合は、 Trace APIを使用できます。このドキュメントでは、 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を返した場合は、UIに移動して、スパン属性service.name = Test Service Aを使用したテスト データのクエリを確認します。

    ヒント

    トレースは、トレースオブザーバーとトレースAPIの両方で処理されるため、最大で1分かかることがあります。

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

Trace API JSON ペイロードはオブジェクトの配列であり、各オブジェクトは単一のトレースを表します。これらの各オブジェクトにはspansキーが必要で、 commonキーが含まれる場合もあります。spans (必須) にはオブジェクトの配列が含まれ、各オブジェクトはスパンを表します。common (オプション) 複数のスパンで情報を共有します。

spans配列の Span オブジェクト

フィールド

タイプ

description

必須

デフォルト

id

ストリング

このスパンの一意の識別子。

そう

該当なし

trace.id

ストリング

1つのトレース内のすべてのスパンで共有される一意の識別子。

そう

該当なし

timestamp

長さ

スパンの開始時間をUnixエポックからのミリ秒単位で表示.

ノー

UTCタイムゾーンでの現在時刻

attributes

物体

スパンに関する詳細を追加するキーと値のペアの任意のセット。duration.msname 、およびparent.idを追加することを強くお勧めします。

ノー

該当なし

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

commonオブジェクト (オプション)

フィールド

タイプ

description

必須

デフォルト

attributes

物体

ペイロード内のスパンに関する共通の詳細を追加するキーと値のペアの任意のセット。スパンにcommonで設定された属性が含まれる場合、スパン属性オブジェクトのキーが優先されます。duration.msname 、およびparent.idを追加することを強くお勧めします。

ノー

該当なし

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

属性

デフォルト

description

duration.ms

浮く

なし

スパンの長さをミリ秒単位で指定します。

name

ストリング

なし

このスパンの名前です。

parent.id

ストリング

なし

このスパンの呼び出し元の ID。これがルート スパンの場合、値はnullです。ルート スパンのないトレースは表示されません。

service.name

ストリング

なし

このスパンを作成したエンティティの名前。値または空の文字列が指定されていない場合、スパンは「UNKNOWN」エンティティに割り当てられ、UI にそのように表示されます。UI で完全なエクスペリエンスを得るには、この値を指定する必要があります。

予約属性

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

属性

デフォルト

description

entity.name

ストリング

service.name

これはservice.name属性から派生します。

entity.type
string

service

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

entity.guid

ストリング

なし

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

その他の属性

制限された属性を除いて、 commonまたは各スパン オブジェクトのattributesオブジェクトに必要な任意の属性を追加できます。たとえば、 customer.iduser.idなどの属性を追加して、トレース データの分析に役立てることができます。

newrelic形式を使用したトレース JSON の要件とガイドライン:

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

次の例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 Inc.

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