用途:本技能用于在 dd-trace-js 中为第三方库新增或修改 APM 自动追踪集成,适用于需要 instrument 库、创建 instrumentation 或插件时。dd-trace-js 为 100 多个第三方库提供自动追踪。
架构:集成由两层解耦组成,通过 Node.js 诊断通道通信。Instrumentation(packages/datadog-instrumentations/src/)钩住库内部方法并向命名通道发布事件,本身不了解追踪;Plugin(packages/datadog-plugin-<name>/src/)订阅通道事件并创建 APM span,设置服务名、资源、标签和错误元数据。新增集成两层都需要。
实现方式:新 instrumentation 默认必须使用 Orchestrion(AST 重写器,通过 JSON 配置自动包装方法,正确处理 CJS 与 ESM),配置位于 packages/datadog-instrumentations/src/helpers/rewriter/instrumentations/<name>.js。只有在 Orchestrion 无法处理时才用 shimmer,并需注释说明原因,如动态方法拦截、工厂模式、参数修改。
插件基类:需按库类型选择,如 CompositePlugin、LogPlugin、WebPlugin/RouterPlugin、TracingPlugin、InboundPlugin/ServerPlugin、OutboundPlugin/ClientPlugin、StoragePlugin、DatabasePlugin、CachePlugin 等,选错基类会带来复杂变通。
关键概念:ctx 对象在两层间传递上下文;通道事件生命周期中,start 事件用 runStores() 建立异步上下文,finish/error 用 publish();hasSubscribers 守卫用于无插件监听时跳过。通道前缀依方式不同。bindStart/bindFinish 是主要插件方法。
工作流:先阅读同类型 1-2 个参考集成,再实现 instrumentation 与 plugin,在多个文件注册,编写单元测试和 ESM 集成测试,然后运行:PLUGINS="<name>" npm run test:plugins:ci。若需外部服务,先 docker compose up -d。最后验证全部测试通过。调试可用 DD_TRACE_DEBUG=true。
限制:资料未提供具体收费、平台或额外效果信息。