計装ライブラリの使用
アプリを開発する際、作業を加速するためにサードパーティのライブラリやフレームワークを使用することがあるでしょう。 OpenTelemetryを使用してアプリを計装する場合、使用するサードパーティのライブラリやフレームワークにトレース、ログ、メトリクスを手動で追加するために時間を費やすことを避けたいことがあります。
多くのライブラリやフレームワークはすでにOpenTelemetryをサポートしているか、OpenTelemetryの計装を介してサポートされているため、テレメトリーを生成してオブザーバビリティバックエンドにエクスポートできます。
サードパーティのライブラリやフレームワークを使用しているアプリやサービスを計装する場合は、このページの手順に従って、ネイティブに計装されたライブラリと依存関係の計装ライブラリの使用方法を学んでください。
ネイティブに計装されたライブラリを使用する
デフォルトでOpenTelemetryサポートが付属しているライブラリの場合、アプリにOpenTelemetry SDKを追加して設定することで、そのライブラリから発行されるトレース、メトリクス、ログを取得できます。
ライブラリによっては、計装のために追加の構成が必要な場合があります。 詳細はライブラリごとのドキュメントをご覧ください。
OpenTelemetryがネイティブに統合されたJavaScriptライブラリをご存知でしたら、お知らせください。
計装ライブラリの使用
ライブラリがOpenTelemetryを最初から組み込んでいない場合、ライブラリやフレームワークのテレメトリーデータを生成するために計装ライブラリを使用できます。
たとえば、Expressの計装ライブラリは、インバウンドHTTPリクエストに基づいて自動的にスパンを作成します。
セットアップ
各計装ライブラリはNPMパッケージです。 たとえば、インバウンドとアウトバウンドのHTTPトラフィックを計装するためにinstrumentation-expressとinstrumentation-http計装ライブラリをインストールする方法は以下の通りです。
npm install --save @opentelemetry/instrumentation-http @opentelemetry/instrumentation-express
OpenTelemetry JavaScriptでは、auto-instrumentation-nodeとauto-instrumentation-webのメタパッケージも定義されており、すべてのNode.jsまたはWebベースの計装ライブラリを単一のパッケージにバンドルしています。 これは、最小限の労力ですべてのライブラリに自動生成されたテレメトリーを追加する便利な方法です。
npm install --save @opentelemetry/auto-instrumentations-node
npm install --save @opentelemetry/auto-instrumentations-web
これらのメタパッケージを使用すると、依存関係グラフのサイズが増加することに注意してください。必要な計装ライブラリが正確にわかっている場合は、個別の計装ライブラリを使用してください。
登録
必要な計装ライブラリをインストールした後、OpenTelemetry SDK for Node.jsに登録します。
Getting Startedに従った場合、すでにメタパッケージを使用しています。手動計装用にSDKを初期化する手順に従った場合は、instrumentation.ts（またはinstrumentation.js）を以下のように更新してください。
/*instrumentation.ts*/
...
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
const sdk = new NodeSDK({
...
// これによりすべての計装パッケージが登録される
instrumentations: [getNodeAutoInstrumentations()]
});
sdk.start()
/*instrumentation.js*/
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const sdk = new NodeSDK({
...
// これによりすべての計装パッケージが登録される
instrumentations: [getNodeAutoInstrumentations()]
});
個別の計装ライブラリを無効にするには、以下の変更を適用できます。
/*instrumentation.ts*/
...
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
const sdk = new NodeSDK({
...
// これによりすべての計装パッケージが登録される
instrumentations: [
getNodeAutoInstrumentations({
'@opentelemetry/instrumentation-fs': {
enabled: false,
},
}),
],
});
sdk.start()
/*instrumentation.js*/
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const sdk = new NodeSDK({
...
// これによりすべての計装パッケージが登録される
instrumentations: [
getNodeAutoInstrumentations({
'@opentelemetry/instrumentation-fs': {
enabled: false,
},
}),
],
});
個別の計装ライブラリのみをロードするには、[getNodeAutoInstrumentations()]を必要なもののリストに置き換えます。
/*instrumentation.ts*/
...
import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
const sdk = new NodeSDK({
...
instrumentations: [
// Express計装はHTTPレイヤーがインストルメントされることを期待している
new HttpInstrumentation(),
new ExpressInstrumentation(),
]
});
sdk.start()
/*instrumentation.js*/
const { HttpInstrumentation } = require("@opentelemetry/instrumentation-http");
const { ExpressInstrumentation } = require("@opentelemetry/instrumentation-express");
const sdk = new NodeSDK({
...
instrumentations: [
// Express計装はHTTPレイヤーがインストルメントされることを期待している
new HttpInstrumentation(),
new ExpressInstrumentation(),
]
});
設定
一部の計装ライブラリは追加の設定オプションを提供しています。
たとえば、Express計装は、指定されたミドルウェアを無視したり、リクエストフックで自動的に作成されるスパンを強化したりする方法を提供しています。
import { Span } from '@opentelemetry/api';
import {
SEMATTRS_HTTP_METHOD,
SEMATTRS_HTTP_URL,
} from '@opentelemetry/semantic-conventions';
import {
ExpressInstrumentation,
ExpressLayerType,
ExpressRequestInfo,
} from '@opentelemetry/instrumentation-express';
const expressInstrumentation = new ExpressInstrumentation({
requestHook: function (span: Span, info: ExpressRequestInfo) {
if (info.layerType === ExpressLayerType.REQUEST_HANDLER) {
span.setAttribute(SEMATTRS_HTTP_METHOD, info.request.method);
span.setAttribute(SEMATTRS_HTTP_URL, info.request.baseUrl);
}
},
});
/*instrumentation.js*/
const {
SEMATTRS_HTTP_METHOD,
SEMATTRS_HTTP_URL,
} = require('@opentelemetry/semantic-conventions');
const {
ExpressInstrumentation,
ExpressLayerType,
} = require('@opentelemetry/instrumentation-express');
const expressInstrumentation = new ExpressInstrumentation({
requestHook: function (span, info) {
if (info.layerType === ExpressLayerType.REQUEST_HANDLER) {
span.setAttribute(SEMATTRS_HTTP_METHOD, info.request.method);
span.setAttribute(SEMATTRS_HTTP_URL, info.request.baseUrl);
}
},
});
高度な設定については、各計装ライブラリのドキュメントを参照する必要があります。
利用可能な計装ライブラリ
利用可能な計装のリストはレジストリで確認できます。
ライブラリをネイティブに計装
ライブラリにネイティブ計装を追加したい場合は、以下のドキュメントを確認してください。
- コンセプトページLibrariesでは、いつ計装するか、何を計装するかについての洞察を提供します
- 手動計装では、ライブラリのトレース、メトリクス、ログを作成するために必要なコード例を提供します
- Node.jsとブラウザ向けのInstrumentation Implementation Guideには、ライブラリ計装を作成するためのJavaScript固有のベストプラクティスが含まれています
計装ライブラリの作成
アプリケーションのための最初から最後までのオブザーバビリティを持つことが望ましい方法ですが、これが常に可能または望ましいとは限りません。 そのような場合は、インターフェースのラッピング、ライブラリ固有のコールバックの購読、既存のテレメトリーのOpenTelemetryモデルへの変換などのメカニズムを使用して計装呼び出しを注入する計装ライブラリを作成できます。
そのようなライブラリを作成するには、Node.jsとブラウザ向けのInstrumentation Implementation Guideに従ってください。
フィードバック
このページは役に立ちましたか?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!