Using instrumentation libraries

当你开发应用时，可能会使用第三方库和框架来加快开发进度。如果你随后使用 OpenTelemetry 对应用进行插桩，你可能希望避免额外花时间为所用的第三方库和框架手动添加链路、日志和指标。

许多库和框架已经原生支持 OpenTelemetry，或者通过 OpenTelemetry 的插桩获得支持， 因此它们能够生成可导出到可观测性后端的遥测数据。

如果你正在为使用第三方库或框架的应用或服务进行插桩， 请按照以下说明学习如何为你的依赖项使用原生插桩库和插桩库。

使用原生插桩库

如果某个库默认就支持 OpenTelemetry，你只需在应用中添加并配置 OpenTelemetry SDK， 就可以获取该库发出的链路、指标和日志。

该库可能需要一些额外的插桩配置。请查阅该库的文档以了解更多信息。

• Instrumentation for Next.js
• Instrumentation for SvelteKit

Use Instrumentation Libraries

If a library does not come with OpenTelemetry out of the box, you can use instrumentation libraries in order to generate telemetry data for a library or framework.

For example, the instrumentation library for Express will automatically create spans based on the inbound HTTP requests.

Setup

Each instrumentation library is an NPM package. For example, here’s how you can install the instrumentation-express and instrumentation-http instrumentation libraries to instrument inbound and outbound HTTP traffic:

npm install --save @opentelemetry/instrumentation-http @opentelemetry/instrumentation-express

OpenTelemetry JavaScript also defines metapackages auto-instrumentation-node and auto-instrumentation-web, that bundle all Node.js- or web-based instrumentation libraries into a single package. It’s a convenient way to add automatically-generated telemetry for all your libraries with minimal effort:

• Node.js
• Browser

npm install --save @opentelemetry/auto-instrumentations-node

npm install --save @opentelemetry/auto-instrumentations-web

Note, that using those metapackages increases your dependency graph size. Use individual instrumentation libraries if you know exactly which ones you need.

Registration

After installing the instrumentation libraries you need, register them with the OpenTelemetry SDK for Node.js. If you followed the Getting Started you already use the metapackages. If you followed the instructions to initialize the SDK for manual instrumentation, update your instrumentation.ts (or instrumentation.js) as follows:

• TypeScript
• JavaScript

/*instrumentation.ts*/
...
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

const sdk = new NodeSDK({
  ...
  // This registers all instrumentation packages
  instrumentations: [getNodeAutoInstrumentations()]
});

sdk.start()

/*instrumentation.js*/
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');

const sdk = new NodeSDK({
  ...
  // This registers all instrumentation packages
  instrumentations: [getNodeAutoInstrumentations()]
});

To disable individual instrumentation libraries you can apply the following change:

• TypeScript
• JavaScript

/*instrumentation.ts*/
...
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

const sdk = new NodeSDK({
  ...
  // This registers all instrumentation packages
  instrumentations: [
    getNodeAutoInstrumentations({
      '@opentelemetry/instrumentation-fs': {
        enabled: false,
      },
    }),
  ],
});

sdk.start()

/*instrumentation.js*/
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');

const sdk = new NodeSDK({
  ...
  // This registers all instrumentation packages
  instrumentations: [
    getNodeAutoInstrumentations({
      '@opentelemetry/instrumentation-fs': {
        enabled: false,
      },
    }),
  ],
});

To only load individual instrumentation libraries, replace [getNodeAutoInstrumentations()] with the list of those you need:

• TypeScript
• JavaScript

/*instrumentation.ts*/
...
import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";

const sdk = new NodeSDK({
  ...
  instrumentations: [
    // Express instrumentation expects HTTP layer to be instrumented
    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 instrumentation expects HTTP layer to be instrumented
    new HttpInstrumentation(),
    new ExpressInstrumentation(),
  ]
});

Configuration

Some instrumentation libraries offer additional configuration options.

For example, Express instrumentation offers ways to ignore specified middleware or enrich spans created automatically with a request hook:

• 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);
    }
  },
});

You’ll need to refer to each instrumentation library’s documentation for advanced configuration.

Available instrumentation libraries

You can find a list of available instrumentation in the registry.

Instrument a library natively

If you want to add native instrumentation to your library, you should review the following documentation:

• The concept page Libraries provides you with insights on when to instrument and what to instrument
• The manual instrumentation provides you with the required code examples to create traces, metrics and logs for your library
• The Instrumentation Implementation Guide for Node.js and browser contains JavaScript specific best practices for creating library instrumentation.

Create an instrumentation library

While having out of the box observability for an application is the preferred way, this is not always possible or desired. In those cases, you can create an instrumentation library, which would inject instrumentation calls, using mechanisms such as wrapping interfaces, subscribing to library-specific callbacks, or translating existing telemetry into the OpenTelemetry model.

To create such a library follow the Instrumentation Implementation Guide for Node.js and browser.