OpenTelemetry Protocol (OTLP) は、 OpenTelemetryプロジェクト用に設計された汎用テレメトリーデータ配信プロトコルです。 各OpenTelemetry言語 SDK は OTLP エクスポーターを提供しており、 OpenTelemetryコレクターには OTLP レシーバーとエクスポーターがあります。 さらに、OpenTelemetry プロジェクト以外のさまざまなツールでも OTLP エクスポートのサポートが追加されました。
New Relic はネイティブ OTLP インジェストをサポートしており、OpenTelemetry データを New Relic プラットフォームに送信するための推奨方法としてこれを推奨しています。 このページでは、設定、要件、推奨事項など、 New Relicの OTLP サポートについて説明します。
あなたが始める前に
まだ行っていない場合は、無料のNewRelicアカウントにサインアップしてください。
データをレポートする New Relic アカウントのを取得します。 このライセンスキーは、
api-keyヘッダーを構成するときに使用されます。
構成: OTLP エンドポイント、ポート、プロトコル
要件レベル:Required [必須]
OTLP データを New Relic に送信するように設定するには、環境に応じて、以下の表の関連するエンドポイントとポートを使用するように OTLP エクスポーターを設定する必要があります。
エンドポイントを構成するメカニズムはさまざまですが、OpenTelemetry 言語 SDK は通常、 OTEL_EXPORTER_OTLP_ENDPOINT=<INSERT_ENDPOINT>環境変数の設定をサポートしています (詳細については、 OpenTelemetry のドキュメントを参照してください)。
さらに、利用可能な場合は、 OTLP/HTTP バイナリ protobuf バージョンのプロトコルを使用するように OTLP エクスポーターを構成する必要があります。 New Relic は OTLP のすべてのバージョンをサポートしていますが、OTLP/HTTP バイナリ プロトコル バッファは、パフォーマンスが明らかに低下することなく、gRPC よりも堅牢であることが証明されています。
エンドポイントを構成するメカニズムはさまざまですが、OpenTelemetry 言語 SDK は通常、 OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf環境変数の設定をサポートしています (詳細については、 OpenTelemetry のドキュメントを参照してください)。
コレクターを使用している場合は、 otlphttpexporter を使用することをお勧めします。
環境 | gRPC | HTTP | 終点 | サポートされているポート |
|---|---|---|---|---|
US OTLP | ✅ | ✅ |
|
|
EU OTLP | ✅ | ✅ |
|
|
US FedRAMP OTLP | ✅ | ✅ |
|
|
無限のトレース | ✅ | ✅ |
|
|
設定: TLS 暗号化
要件レベル:Required [必須]
OTLP データを New Relic に送信するには、TLS 1.2 を使用するように OTLP エクスポーターを設定する必要があります (詳細については、 TLS 暗号化を参照してください)。 一般に、SDK およびコレクター エクスポーターはデフォルトでこの要件を満たします。
多くの OTLP エクスポータはhttpsエンドポイント スキームから TLS 設定を推測しますが、一部の gRPC エクスポータでは TLS を明示的に有効にする必要がある場合があります。 gRPC TLS を構成するメカニズムはさまざまですが、OpenTelemetry 言語 SDK は通常、 OTEL_EXPORTER_OTLP_INSECURE=false環境変数の設定をサポートしています (詳細については、 OpenTelemetry のドキュメントを参照してください)。
設定: APIキーの設定
要件レベル:Required [必須]
OTLP データをNew Relicに送信するには、ライセンスキーに設定された値を持つ api-key という名前のヘッダーを含めるように OTLP エクスポーターを構成する必要があります。 そうしないと、認証エラーが発生します。
ヘッダーを構成するメカニズムはさまざまですが、OpenTelemetry 言語 SDK は通常、 OTEL_EXPORTER_OTLP_HEADERS=api-key=<INSERT_LICENSE_KEY>環境変数の設定をサポートしています (詳細については、 OpenTelemetry のドキュメントを参照してください)。
設定: 属性の制限
要件レベル:Required [必須]
OTLP データをNew Relicに送信するには、テレメトリ ソースをNew Relicプロパティ制限に準拠するように構成する必要があります。 これを行わないと、非同期データ検証中にNrIntegrationErrorイベントが発生する可能性があります。
属性の制限は次のとおりです。
- 属性名の最大長：255文字
- 属性値の最大長：4095文字
- 属性配列値の最大サイズ: 64 エントリ
その他の制限については、メトリクス 属性 制限およびイベント 属性 制限を参照してください。
属性制限を構成するメカニズムはさまざまですが、OpenTelemetry 言語 SDK は通常、 OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT=4095およびOTEL_ATTRIBUTE_COUNT_LIMIT=64環境変数の設定をサポートしています (詳細については、 OpenTelemetry のドキュメントを参照してください)。
コレクターを使用する場合、属性を New Relic の制限に合わせて切り捨てるように変換プロセッサを構成できます。
メモ：
- リソース属性は属性制限の対象となりますが、それを制限するための標準環境変数はありません。 リソースのプロパティが許可された制限を超えている場合は、コレクター変換プロセッサを使用して切り詰めるか、リソースのプロパティを別の値に上書きすることを検討してください。
- 属性名を制限する標準的なメカニズムはありません。 ただし、インストゥルメンテーションは通常、 New Relic制限を超えるプロパティ名を生成しません。 名前の長さ制限に遭遇した場合は、コレクターを使用して属性を削除します。
設定: ペイロードのバッチ処理、タイムアウト、圧縮、レート制限
要件レベル:Required [必須]
OTLP データをNew Relicに送信するには、ペイロードが最大ペイロード サイズである 1 MB (10^6 バイト) より小さくなければなりません。 大きなペイロードはエラー ステータス コードで拒否されます。 大きなペイロードの場合、エラー ステータス コードが返される前にタイムアウトが発生してエクスポートに失敗することもあります。
さらに、New Relic はレート制限を課します。 レート制限を超えると、リクエストはエラー ステータス コードで拒否されます。
ペイロード サイズの制限とレート制限を回避するには、適切な間隔でデータがエクスポートされる適切なバッチ サイズを使用するように OTLP エクスポーターを構成する必要があります。
バッチ処理を構成するメカニズムは異なります。 OpenTelemetry SDK は通常、次の環境変数の設定をサポートしています (詳細についてはOpenTelemetry のドキュメントを参照してください)。
OTEL_BSP_*スパンのOTEL_METRIC_EXPORT_*メトリクス用OTEL_BLRP_*ログ用
コレクターを使用する場合、 バッチ プロセッサがバッチ サイズを制御します。
さらに、エクスポーターのタイムアウト設定にも注意する必要があります。 一般的に、ペイロードが大きい場合やネットワークが遅い場合 (レイテンシが高い、帯域幅が低い)、エクスポート リクエストにかかる時間は長くなります。 テレメトリの量が多いかエクスポート間隔が長いためにアプリケーションが大量のペイロードを生成する場合は、エクスポート エラーを回避するためにデフォルトのタイムアウト設定を増やす必要がある場合があります。
タイムアウトを構成するメカニズムはさまざまですが、OpenTelemetry 言語 SDK は通常、 OTEL_EXPORTER_OTLP_TIMEOUT環境変数の設定をサポートしています (詳細については、 OpenTelemetry のドキュメントを参照してください)。
さらに、ペイロード サイズを縮小し、ペイロード サイズの制限に遭遇する可能性を制限するために、圧縮を有効にする必要があります。 New Relic はgzipおよびzstd圧縮をサポートしています。 zstd圧縮はパフォーマンスが高く、エクスポーターがサポートしている場合は推奨されます。 ベンチマーク情報の詳細については、 圧縮の比較を参照してください。
エンドポイントを構成するメカニズムはさまざまですが、OpenTelemetry 言語 SDK は通常、 OTEL_EXPORTER_OTLP_COMPRESSION=gzip環境変数の設定をサポートしています (詳細については、 OpenTelemetry のドキュメントを参照してください)。
コレクターを使用する場合、 gzipがデフォルトの圧縮ですが、オプションでzstdを構成できます。
設定: 再試行
要件レベル:Recommended [推奨]
OTLP データを New Relic に送信するには、一時的なエラーが発生したときに再試行するように OTLP エクスポーターを構成する必要があります。 インターネットは信頼性が低く、再試行に失敗するとデータが失われる可能性が高くなります。
再試行を構成するメカニズムは異なります。 一部の OpenTelemetry SDK には言語固有の環境変数がある場合がありますが (たとえば、 java はOTEL_EXPERIMENTAL_EXPORTER_OTLP_RETRY_ENABLED=true設定をサポートしています)、一般的なメカニズムはありません。 プログラムによる設定が必要になる場合があります。
コレクターを使用する場合、 otlphttpexporterとotlpexporterはデフォルトで再試行されます。 詳細についてはexporterhelperを参照してください。
設定: メトリクス集約時間
要件レベル:Recommended [推奨]
OTLP メトリックス データをNew Relicに送信するには、デルタ集計の時間性を優先するように OTLP メトリックス エクスポーターを構成する必要があります。 New Relic累積集計時間性をサポートしていますが、 New Relicメトリックス アーキテクチャーは一般的にデルタ メトリックス システムです。 デフォルトの累積設定を使用すると、通常、SDK からのメモリ使用量が増加し、データの取り込み量が多くなります。
エンドポイントを構成するメカニズムはさまざまですが、OpenTelemetry 言語 SDK は通常、 OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta環境変数の設定をサポートしています (詳細については、 OpenTelemetry のドキュメントを参照してください)。 手動で時間を設定する場合は、計装の種類ごとに次のように設定します。
- カウンター、非同期カウンター、ヒストグラム: デルタ
- UpDownCounter、非同期 UpDownCounter、ゲージ、非同期ゲージ: 累積
累積時間性は、 New Relicゲージ タイプにマッピングされるインストゥルメントで使用され、一般に累積値を使用して分析されます。
構成: メトリクス ヒストグラム集計
要件レベル:Recommended [推奨]
OTLP メトリックス データをNew Relicに送信するには、ヒストグラム インストゥルメントされた測定値を指数ヒストグラムに集約するように OTLP メトリックス エクスポーターを構成する必要があります。 デフォルトの明示的なバケット ヒストグラムで使用される静的バケットとは対照的に、指数ヒストグラムは記録された測定値の範囲を反映するようにバケットを自動的に調整します。 さらに、ネットワーク経由で送信するために、高度に圧縮された表現を使用します。 指数ヒストグラムは、New Relic プラットフォームでより有用な分布データを提供します。
エンドポイントを構成するメカニズムはさまざまですが、OpenTelemetry 言語 SDK は通常、 OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION=base2_exponential_bucket_histogram環境変数の設定をサポートしています (詳細については、 OpenTelemetry のドキュメントを参照してください)。
OTLPプロトコルバージョン
New Relic は OTLP リリースv1.4.0を使用します。 それ以降のバージョンと以前のバージョンはサポートされていますが、新しい機能はまだ実装されていません。 0.18.0 以降に削除された実験的な機能はサポートされていません。
データがどのようにマッピングされるか、どの機能が実装されるかについての具体的な詳細については、トレース、メトリクス、ログを参照してください。
OTLP 属性タイプ
属性は、OpenTelemetry と OTLP で繰り返し登場する概念です。 OpenTelemetry には標準の属性定義があり、属性値はプリミティブ (文字列、ブール値、倍精度浮動小数点数、64 ビット整数) またはプリミティブの同種配列であると規定されています。 ただし、OTLP プロトコル レベルでは、属性はより拡張されたAnyValue定義を使用して表されます。 このため、OTLP クライアントが OpenTelemetry 標準定義に準拠していない属性を送信する可能性があります。
New Relic OTLP エンドポイントは標準の属性定義をサポートしています。 マップのマップ、オブジェクト配列、異種配列などの複雑な型はサポートされていません。 OpenTelemetry SDK は、標準の属性定義に準拠したデータのみを生成する必要があります。
重要
一般に標準のプロパティ定義が使用されますが、ログ レコード プロパティは例外であり、複雑な値をサポートします (たとえば、ログ レコード プロパティ タイプはmap<string, any> )。 それにもかかわらず、 New Relic現在、標準のプロパティ定義に準拠するログ レコード プロパティのみをサポートしています。
OTLP 応答ペイロード
New Relic OTLP エンドポイント応答ペイロードに関する次の詳細に注意してください。
- New Relic からの成功した応答には、データ タイプに基づいてProtobuf でエンコードされた応答ではなく、応答本文が含まれません。
- New Relic は、認証、ペイロード サイズ、レート制限の検証後に応答します。 ペイロードの内容の検証は非同期で行われます。 したがって、データの取り込みが最終的に失敗し、
NrIntegrationErrorイベントが発生したにもかかわらず、New Relic は成功ステータス コードを返す場合があります。 - New Relic からの失敗応答には
Status.messageまたはStatus.details含まれません。