計装ライブラリの使用

When you develop an app, you might use third-party libraries and frameworks to accelerate your work. If you then instrument your app using OpenTelemetry, you might want to avoid spending additional time to manually add traces, logs, and metrics to the third-party libraries and frameworks you use.

Many libraries and frameworks already support OpenTelemetry or are supported through OpenTelemetry instrumentation, so that they can generate telemetry you can export to an observability back end.

If you are instrumenting an app or service that use third-party libraries or frameworks, follow these instructions to learn how to use natively instrumented libraries and instrumentation libraries for your dependencies.

Use natively instrumented libraries

If a library comes with OpenTelemetry support by default, you can get traces, metrics, and logs emitted from that library by adding and setting up the OpenTelemetry SDK with your app.

The library might require some additional configuration for the instrumentation. Go to the documentation for that library to learn more.

• Instrumentation for Next.js

計装ライブラリの使用

ライブラリが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ベースの計装ライブラリを単一のパッケージにバンドルしています。 これは、最小限の労力ですべてのライブラリに自動生成されたテレメトリーを追加する便利な方法です。

• Node.js
• Browser

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）を以下のように更新してください。

• TypeScript
• JavaScript

/*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()]
});

個別の計装ライブラリを無効にするには、以下の変更を適用できます。

• TypeScript
• JavaScript

/*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()]を必要なもののリストに置き換えます。

• TypeScript
• JavaScript

/*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計装は、指定されたミドルウェアを無視したり、リクエストフックで自動的に作成されるスパンを強化したりする方法を提供しています。

• TypeScript
• JavaScript

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に従ってください。