使用仪器库
在开发应用程序时，您可能会使用第三方库和框架来加速您的工作。如果您随后使用 OpenTelemetry instrumentation 您的应用程序，您可能希望避免花费额外的时间手动为您使用的第三方库和框架添加 traces、logs 和 metrics。
许多库和框架已经支持 OpenTelemetry，或者通过 OpenTelemetry instrumentation 进行支持，因此它们可以生成您可以导出到可观测性后端的 telemetry。
如果您正在 instrumentation 使用第三方库或框架的应用程序或服务，请遵循以下说明，了解如何为您的依赖项使用原生 instrumented 库和 instrumentation 库。
使用原生 instrumented 库
如果一个库默认包含 OpenTelemetry 支持，您可以通过在您的应用程序中添加和设置 OpenTelemetry SDK 来获取该库发出的 traces、metrics 和 logs。
该库可能需要一些额外的配置来进行 instrumentation。请参阅该库的文档以了解更多信息。
如果您知道有 JavaScript 库原生集成了 OpenTelemetry，请告知我们。
使用检测库
如果某个库默认不包含 OpenTelemetry，您可以使用 检测库 来为某个库或框架生成遥测数据。
例如，Express 的仪表盘库会根据传入的 HTTP 请求自动创建Span。
设置
每个仪表盘库都是一个 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
请注意，使用这些元包会增加您的依赖图的大小。如果您确切知道需要哪些单独的仪表盘库，请使用它们。
注册
在安装完所需的仪表盘库后，将其注册到 Node.js 的 OpenTelemetry SDK。如果您遵循了入门指南，那么您已经在使用元包了。如果您遵循了初始化 SDK 进行手动仪表盘的说明，请按以下方式更新您的 instrumentation.ts（或 instrumentation.js）文件
/*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()]
});
要禁用单个仪表盘库，您可以进行以下更改
/*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,
},
}),
],
});
要仅加载单个仪表盘库，请将 [getNodeAutoInstrumentations()] 替换为您需要的库列表
/*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(),
]
});
配置
一些仪表盘库提供额外的配置选项。
例如，Express 仪表盘提供了忽略指定中间件或使用请求钩子丰富自动创建的 Span 的方法
import { Span } from '@opentelemetry/api';
import {
ATTR_HTTP_REQUEST_METHOD,
ATTR_URL_FULL,
} 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(ATTR_HTTP_REQUEST_METHOD, info.request.method);
span.setAttribute(ATTR_URL_FULL, info.request.baseUrl);
}
},
});
/*instrumentation.js*/
const {
ATTR_HTTP_REQUEST_METHOD,
ATTR_URL_FULL,
} = 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(ATTR_HTTP_REQUEST_METHOD, info.request.method);
span.setAttribute(ATTR_URL_FULL, info.request.baseUrl);
}
},
});
您需要查阅每个仪表盘库的文档以了解高级配置。
可用检测库
您可以在注册中心找到可用仪表盘的列表。
原生集成库
如果您想为您的库添加原生集成，您应该查阅以下文档
- 概念页面库为您提供了关于何时集成以及集成什么的见解
- 有关手动集成的代码示例，可用于为您的库创建跟踪、指标和日志
- Node.js 和浏览器仪表盘实现指南包含创建库集成的 JavaScript 特定最佳实践。
创建仪表盘库
虽然开箱即用的应用程序可观察性是首选方式，但这并非总是可能或可取的。在这些情况下，您可以创建一个仪表盘库，该库将使用诸如包装接口、订阅特定于库的回调或将现有遥测转换为 OpenTelemetry 模型等机制来注入仪表盘调用。
要创建此类库，请遵循 Node.js 和浏览器仪表盘实现指南。