雀巢JS 开口遥测
这个图书馆,原来是叉子的 从 @ overbit/ opetetometry- nestjs (英语),提供无缝 雀巢JS应用的OpenTeleometry集成,包括自动追踪和度量衡.
说明
为NestJS(协议-不可知框架)所设计,这个库跨越了HTTP,GRPC,RabbitMQ等协议. 它使NestJS特有的地层具有高度的可观察性, 包括 主计长, (中文(简体) ), 警卫, (中文(简体) ), 截取器, (中文(简体) ), 管道, (中文(简体) ), 财务报告和审定财务报表 供应商。 。 。 .
此外,它还为广泛使用的NestJS图书馆提供自动跟踪和计量仪器,帮助您 以最小配置监视和分析您的应用程序.
安装
npm install @amplication/opentelemetry-nestjs --save
支持NestJS 10,11和12上节点.js QQ 20.19. @nestjs/graphql, (中文(简体) ), @nestjs/microservices, (中文(简体) ),
@nestjs/schedule 财务报告和审定财务报表 @nestjs/platform-express 是可选的对等器 - 只在您的应用程序使用时安装它们 .
设置
开始 @amplication/opentelemetry-nestjs 很简单。 用于大多数 NestJS 的自动仪器
组件,只需导入 OpenTelemetryModule 在您的根模块中 :
import { OpenTelemetryModule } from '@amplication/opentelemetry-nestjs';
@Module({
imports: [OpenTelemetryModule.forRoot()],
})
export class AppModule {}
这将自动显示仪器控制器、 提供者、 守卫、 截取器和其他核心 NestJS 层 你的观察力出盒.
[TIP] 这个库只有乐器 NestJS 代码. 确保 页:1 打开遥测节点 SDK 已安装 适当初始化以收集痕迹和度量衡。 此软件包也 提供 帮助者 对于它.
使用量
当此库自动显示乐器核心 NestJS 层时, 您可以使用 @Traceable 财务报告和审定财务报表 @Span 装饰器改为
创建特定方法的自定义跨度,例如提供者函数。 这样你就可以给人有意义的名字了
并且捕捉到重要行动的精细痕迹.
@Span
import { Injectable } from '@nestjs/common';
import { Span } from '@amplication/opentelemetry-nestjs';
@Injectable()
export class AppService {
@Span()
getHello(): string {
return 'Hello World!';
}
@Span('SpecialCase')
getSpecial(): string {
return 'Never miss a SpecialCase with its fancy name!';
}
}
@Traceable
@Traceable 喜欢 @Span 但不同的是,它可以用于一个类级 自动仪器每
类别方法:
import { Injectable } from '@nestjs/common';
import { Traceable } from '@amplication/opentelemetry-nestjs';
@Traceable()
@Injectable()
export class AppService {
getHello(): string {
return 'Hello World!';
}
}
Tracer
在高级使用的情况下, 您需要访问本地的 OpenTelemetry 微量服务商才能从 NestJS 访问它们
应用程序上下文。 这样的话,你可以注射 Tracer 提供者 :
import { Injectable } from '@nestjs/common';
import { Tracer } from '@amplication/opentelemetry-nestjs';
@Injectable()
export class AppService {
constructor(private readonly tracer: Tracer) {}
getHello(): string {
const span = this.tracer.startSpan('important_section_start');
// do something important
span.setAttributes({ userId: 1150 });
span.end();
return 'Hello World!';
}
}
TraceService
这个 TraceService 直接访问当前跨度上下文,并允许您开始自定义跨度:
import { Injectable } from '@nestjs/common';
import { TraceService } from '@amplication/opentelemetry-nestjs';
@Injectable()
export class AppService {
constructor(private readonly traceService: TraceService) {}
getHello(): string {
const span = this.traceService.startSpan('hello');
// do something
span.end();
return 'Hello World!';
}
}
自动跟踪仪器
图书馆配有全面的"巢"JS仪器出库. 一旦您导入模块,控制器, 警卫、供应商、管道和其他核心部件自动追踪.
如果您想要自定义启用的仪器, 您可以使用 instrumentation 选项 :
import { Module } from '@nestjs/common';
import {
OpenTelemetryModule,
ControllerInstrumentation,
EventEmitterInstrumentation,
GuardInstrumentation,
LoggerInstrumentation,
PipeInstrumentation,
ScheduleInstrumentation,
} from '@amplication/opentelemetry-nestjs';
@Module({
imports: [
OpenTelemetryModule.forRoot({
instrumentation: [
ControllerInstrumentation,
GuardInstrumentation,
EventEmitterInstrumentation,
ScheduleInstrumentation,
PipeInstrumentation,
LoggerInstrumentation,
],
}),
],
})
export class AppModule {}
仪器组件
| 实例 | 说明 |
|---|---|
ControllerInstrumentation | 自动跟踪所有模块控制器 |
GuardInstrumentation | 自动追踪包括全球警卫在内的所有模块警卫 |
PipeInstrumentation | 自动跟踪所有模块管,包括全球管 |
InterceptorInstrumentation | 自动追踪所有模块拦截器,包括全球管道 |
EventEmitterInstrumentation | 自动跟踪 @nestjs/事件内容 库,支持所有特性 |
ScheduleInstrumentation | 自动跟踪 @ nestjs/ 时间表 库,支持所有特性 |
ConsoleLoggerInstrumentation | 控制台 财务报告和审定财务报表 锁定器 类跟踪器,带有跟踪仪的日志 |
使用 Track ID 登录
通过启用 ConsoleLogger 仪器(或使用默认配置),所有日志将自动包含 当前痕量标识, 从而更容易将日志与痕量联系起来 :
非注射类的人工追踪
如果您需要追踪未由 NestJS DI 容器管理的类别, 您可以将实例包入
TraceWrapper.trace()。这自动为每种方法创建一个新的跨度:
import { TraceWrapper } from '@amplication/opentelemetry-nestjs';
class MyClass {
hello() {
console.log('Hi');
}
async bye() {
await new Promise(() => console.log('bye bye'));
}
}
// ....
const instance = new MyClass();
const tracedInstance = TraceWrapper.trace(instance);
// ....
计量
您可以使用 Prometheus 输出器来建立测量收集 。 首先,安装Prometheus出口商包:
npm install @opentelemetry/exporter-prometheus
然后,在您的 OpenTelemotry 节点 SDK 中配置它 :
new NodeSDK({
serviceName: 'nestjs-opentelemetry-example',
// ...
metricReader: new PrometheusExporter({
endpoint: 'metrics',
port: 9464,
}),
});
您现在可以通过 Prometheus 导出器访问自动收集的度量衡 时间 http://localhost:9464/meters (英语)。 。 。 .
其他出口选择见 页:1 OpenTeleometry JavaScript 导出文档。 。 。 .
启动 OpenTeleometry SDK
在典型的为节点(Node.js)设置的 OpenTeleometry 中,通常会创建一个 tracing.ts (或类似名称)文件
初始化并配置 SDK。 此文件应导入 在最顶端 main.ts,在任何其他时间之前
输入,以便所有装入后的模块和库都有适当的仪器。 这样做可以确保跨度
为您的应用程序的操作而正确创建,且上下文传播和自动仪器为
从进程开始活动.
此软件包提供了一套辅助功能,用于简化 OpenTelemeting 节点 SDK 的启动和配置 NestJS应用. 它包括上下文管理、宣传器、资源探测、自动仪器和跨度 加工——并可以大大减少痕迹中的噪音.
startNestJsOpenTelemetrySDK(configuration)
以默认的 NestJS 方便助手启动节点 OpenTelemeting SDK, 包括自动仪器, 上下文
管理器、宣传器和资源探测器。 接受任意 NodeSDKConfiguration 覆盖 :
示例
import { startNestJsOpenTelemetrySDK } from '@amplication/opentelemetry-nestjs';
import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
const sdk = startNestJsOpenTelemetrySDK({
serviceName: 'nestjs-example',
metricReader: new PrometheusExporter({ endpoint: 'metrics', port: 9464 }),
});
startNestJsOpenTelemetrySDK 相当于以下内容:
import { NodeSDK } from '@opentelemetry/sdk-node';
import {
nodeAutoInstrumentationReduceNoise,
nodeAutoInstrumentationHttpReduceIncoming,
nestjsContextManager,
nestjsTextMapPropagator,
nestjsResourceDetectors,
} from '@amplication/opentelemetry-nestjs';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
const sdk = new NodeSDK({
instrumentations: getNodeAutoInstrumentations(
mergeInstrumentationConfigMap(
nodeAutoInstrumentationReduceNoise(),
nodeAutoInstrumentationHttpReduceIncoming(),
),
),
contextManager: nestjsContextManager(),
textMapPropagator: nestjsTextMapPropagator(),
resourceDetectors: nestjsResourceDetectors(),
});
sdk.start();
nodeAutoInstrumentationReduceNoise()
返回预配置的一套降噪的节点自动装置:
fs仪器忽略文件node_modules和标签之间有文件路径.http仪器更新收到的请求跨度至"HTTP_METHOD PATH"。 。 。 .graphql为 NestJS 配置了仪器(mergeItems: true, (中文(简体) ),ignoreResolveSpans: true, (中文(简体) ),ignoreTrivialResolveSpans: true) (中文(简体) ).net, (中文(简体) ),dns, (中文(简体) ),express,以及nestjs-core仪器被禁用以减少噪音.
示例
import { nodeAutoInstrumentationReduceNoise } from '@amplication/opentelemetry-nestjs';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
const instrumentations = getNodeAutoInstrumentations(
nodeAutoInstrumentationReduceNoise(),
);
nodeAutoInstrumentationHttpReduceIncoming(options?)
过滤从跟踪中收到的特定HTTP请求,例如健康检查或选择方案请求.
选项 :
healthChecks: 需要忽略的 URL 路径数组(['/health', '/_health', '/healthz', 'healthcheck'](默认)methods: 忽略的 HTTP 方法的阵列 (['OPTIONS'](默认)
示例
import { nodeAutoInstrumentationHttpReduceIncoming } from '@amplication/opentelemetry-nestjs';
const httpInstrumentations = nodeAutoInstrumentationHttpReduceIncoming({
healthChecks: ['/health', '/status'],
methods: ['OPTIONS'],
});
nestjsContextManager()
返回 a AsyncLocalStorageContextManager 在Async NestJS代码中进行适当的上下文传播.
示例
import { nestjsContextManager } from '@amplication/opentelemetry-nestjs';
const contextManager = nestjsContextManager();
nestjsTextMapPropagator()
返回一个复合传播器,支持:
- 贾格
- W3C 追踪上下文
- B3 单头和多头
示例
import { nestjsTextMapPropagator } from '@amplication/opentelemetry-nestjs';
const propagator = nestjsTextMapPropagator();
nestjsResourceDetectors()
返回一系列资源探测器,以丰富环境信息(目前包括
containerDetector) (中文(简体) ).
示例
import { nestjsResourceDetectors } from '@amplication/opentelemetry-nestjs';
const detectors = nestjsResourceDetectors();
mergeInstrumentationConfigMap(target, source)
递归地将两个仪器配置对象合并. 用于将自定义自动仪器选项与 默认.
示例
import {
mergeInstrumentationConfigMap,
nodeAutoInstrumentationReduceNoise,
} from '@amplication/opentelemetry-nestjs';
const customConfig = {
'@opentelemetry/instrumentation-http': {
ignoreIncomingRequestHook: (req) => req.url === '/metrics',
},
};
const merged = mergeInstrumentationConfigMap(
nodeAutoInstrumentationReduceNoise(),
customConfig,
);
实例
/* tracing.ts */
import { startNestJsOpenTelemetrySDK } from '@amplication/opentelemetry-nestjs';
import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc';
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node';
import { CompositePropagator } from '@opentelemetry/core';
import { JaegerPropagator } from '@opentelemetry/propagator-jaeger';
import { B3InjectEncoding, B3Propagator } from '@opentelemetry/propagator-b3';
startNestJsOpenTelemetrySDK({
serviceName: 'myservice-opentelemetry-example',
metricReader: new PrometheusExporter({
endpoint: 'metrics',
port: 9464,
}),
spanProcessors: [
new BatchSpanProcessor(
new OTLPTraceExporter({
url: 'your-jaeger-url',
}),
),
],
textMapPropagator: new CompositePropagator({
propagators: [
new JaegerPropagator(),
new B3Propagator(),
new B3Propagator({
injectEncoding: B3InjectEncoding.MULTI_HEADER,
}),
],
}),
});
import { NestFactory } from '@nestjs/core';
// ....
/* at the very top of main.ts */
import 'tracing.ts';
// ...
/* app.module.ts */
import { Module } from '@nestjs/common';
import { OpenTelemetryModule } from '@amplication/opentelemetry-nestjs';
@Module({
imports: [OpenTelemetryModule.forRoot()],
})
export class AppModule {}
AWS X-Ray/ 云层监视
关于与AWS X-Ray和Cloud Watch的集成,请遵循 页:1 官方指示数字 :
/* tracing.ts */
import {
startNestJsOpenTelemetrySDK,
defaultInstrumentation,
} from '@amplication/opentelemetry-nestjs';
import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc';
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node';
import { CompositePropagator } from '@opentelemetry/core';
import { AWSXRayPropagator } from '@opentelemetry/propagator-aws-xray';
import { AWSXRayIdGenerator } from '@opentelemetry/id-generator-aws-xray';
import { AwsInstrumentation } from '@opentelemetry/instrumentation-aws-sdk';
startNestJsOpenTelemetrySDK({
serviceName: 'myservice-opentelemetry-example',
metricReader: new PrometheusExporter({
endpoint: 'metrics',
port: 9464,
}),
instrumentations: [
...defaultInstrumentation,
new AwsInstrumentation({
suppressInternalInstrumentation: true,
sqsExtractContextPropagationFromPayload: true,
}),
],
idGenerator: new AWSXRayIdGenerator(),
spanProcessors: [new BatchSpanProcessor(new OTLPTraceExporter({}))],
textMapPropagator: new AWSXRayPropagator(),
});
从v6.x迁移到v7.x
7.0版本没有API修改. 它减少了对NestJS 8和9的支持,并增加了对NestJS 12和
@nestjs/graphql 13.4+ / 14 (中文(简体) )
- 支持的版本: NestJS 10、11和12 (中文(简体) )
@nestjs/graphql12-14, (中文(简体) ),@nestjs/event-emitter第2、3和12条,@nestjs/schedule页:1 节点.js QQ 20. 19 是需要的, 它允许这个 CommunityJS 包装入 仅限无害环境管理的NestJS 12套软件. - 可选同伴数字 :
@nestjs/graphql, (中文(简体) ),@nestjs/microservices, (中文(简体) ),@nestjs/schedule财务报告和审定财务报表@nestjs/platform-express不再自动安装。 如果使用的话, 添加到应用程序的依赖性中 . - 不再进口: 包不再深入
@nestjs/graphql/dist/...或者说@nestjs/microservices/constants,与软件包相撞exports引入的地图@nestjs/graphql13.4. (中文(简体) ).
从v5.x迁移到v6.x
6.0版本引入了重大的突破性修改来提高类型安全性,与OpenTeleometry标准保持一致,并增强代码组织.
📖 《移徙指南》全文
变化的快速摘要
- SDK 启动数字 :
Tracing.init()→startNestJsOpenTelemetrySDK() - 模块配置: 矩阵格式 = 对象格式
instrumentation属性 - 命名页:1
*Injector科目 −*Instrumentation - 进口: 文件路径已更新到 kebab 大小写
- 追踪命名: 已更新以与 OpenTeleometry 语义公约保持一致
在(v5.x)之前:
Tracing.init({ serviceName: 'my-app' });
OpenTelemetryModule.forRoot([ControllerInjector]);
在(v6.x)之后:
startNestJsOpenTelemetrySDK({ serviceName: 'my-app' });
OpenTelemetryModule.forRoot({ instrumentation: [ControllerInstrumentation] });
关于详细的迁移指示、代码示例和完整的核对表,见 移徙指南。 。 。 .