使用插桩库
当你开发应用时，可能会使用第三方库和框架来加快开发进度。如果你随后使用 OpenTelemetry 对应用进行插桩，你可能希望避免额外花时间为所用的第三方库和框架手动添加链路、日志和指标。
许多库和框架已经原生支持 OpenTelemetry，或者通过 OpenTelemetry 的插桩获得支持， 因此它们能够生成可导出到可观测性后端的遥测数据。
如果你正在为使用第三方库或框架的应用或服务进行插桩， 请按照以下说明学习如何为你的依赖项使用原生插桩库和插桩库。
使用原生插桩库
如果某个库默认就支持 OpenTelemetry，你只需在应用中添加并配置 OpenTelemetry SDK， 就可以获取该库发出的链路、指标和日志。
该库可能需要一些额外的插桩配置。请查阅该库的文档以了解更多信息。
如果你知道某个 JavaScript 库已原生集成了 OpenTelemetry，请告诉我们。
使用插桩库
如果一个库没有提供 OpenTelemetry 开箱即用的支持，你可以使用插桩库来为该库或框架生成遥测数据。
例如， Express 插桩库会根据入站 HTTP 请求自动创建 Span。
安装
每个插桩库都是一个 NPM 包。例如，下面是如何安装 Express 插桩库 和 HTTP 插桩库 来为入站和出站 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({
...
// 这里注册所有插桩库
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 插桩 提供了可以忽略指定的中间件或通过请求钩子为自动生成的追踪 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);
}
},
});
你需要参考每个插桩库的文档以获取高级配置说明。
可用的插桩库
你可以在注册表中找到可用的插桩库列表。
对库进行原生插桩
如果要为库添加原生插桩，你应该参考以下文档：
创建一个插桩库
虽然为应用提供开箱即用的可观测性是理想方案，但这并非在所有情况下都可行或符合需求。 在这些场景下，你可以创建一个插桩库，该库会通过各种机制注入插桩调用，例如包装接口、订阅库专属回调函数，或是将现有遥测数据转换为 OpenTelemetry 数据模型。
创建这样的库请参考 Node.js 和浏览器的插桩实现指南。
意见反馈
这个页面对您有帮助吗？
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!