NocoBase Telemetry 遥测模块详解基于 OpenTelemetry 构建可观测性指标与链路追踪【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobaseNocoBase 通过nocobase/telemetry包提供内置的遥测Telemetry能力它是应用级可观测性体系的入口负责注册 OpenTelemetry 生态的插桩Instrumentation并统一初始化和管理指标Metric与链路Trace两套子系统。读完本文你可以掌握Telemetry类的完整 API 与配置项理解 NocoBase 应用启动时遥测是如何被创建、启用和关闭的并能基于Trace/Metric的注册器机制扩展自定义的 Span 处理器与 Metric 读取器。模块概览Telemetry是 NocoBase 的遥测模块基于 OpenTelemetry 封装支持注册 OpenTelemetry 生态的指标Metric和链路Trace工具。其核心实现位于 packages/core/telemetry共包含三个文件telemetry.tsTelemetry主类与TelemetryOptions接口负责协调插桩注册、Resource 构建以及 Trace/Metric 的生命周期trace.tsTrace类封装NodeTracerProvider与 Span 处理器注册机制metric.tsMetric类封装MeterProvider与 Metric 读取器注册机制。入口文件 index.ts 统一导出Telemetry、Trace、Metric及相关选项类型并额外转出 OpenTelemetry 的PeriodicExportingMetricReader与Meter方便插件在二次开发时直接复用这些底层工具。constructor()构造函数与 TelemetryOptions构造函数用于创建一个Telemetry实例签名为constructor(options?: TelemetryOptions)选项类型定义如下与 telemetry.ts 中的接口一致export interface TelemetryOptions { serviceName?: string; version?: string; trace?: TraceOptions; metric?: MetricOptions; }各属性说明如下属性类型描述默认值serviceNamestring可选参考 OpenTelemetry 的 Semantic Conventionsservice.name资源属性nocobaseversionstring可选参考 OpenTelemetry 的 Semantic Conventionsservice.version资源属性可选当前 NocoBase 版本号traceTraceOptions可选链路追踪配置参考 Trace 文档metricMetricOptions可选指标配置参考 Metric 文档从源码实现看构造函数还会做两件事见 telemetry.ts内部自动创建Trace与Metric实例Tracer/Meter 名称会基于服务名派生tracerName默认为${serviceName}-tracemeterName默认为${serviceName}-meter源码中的TelemetryOptions接口还包含一个appName字段用于标记所属 NocoBase 应用名写入 Resource 的app.name属性该字段由框架在构建实例时自动注入插件侧一般无需手动设置。init()注册插桩并初始化 Trace / Metricinit(): void用于注册 Instrumentation并初始化Trace、Metric。其内部流程telemetry.ts可以概括为三步调用 OpenTelemetry 的registerInstrumentations把此前通过addInstrumentation()收集到的插桩库统一注册通过resourceFromAttributes构建 OpenTelemetry 的Resource写入三类资源属性service.name来自serviceName、service.version来自version和app.name来自appName将该 Resource 分别传给Trace.init(resource)与Metric.init(resource)作为后续 Span 与 Metric 数据的服务身份标识。需要注意的调用约束Trace与Metric的start()方法都会检查 Resource 是否已注入若init()未先于start()调用会直接抛出Trace.init(resource) must be called before start()或对应的 Metric 版本错误。也就是说init()是start()的前置条件不能跳过。start()启动数据处理程序start(): void启动Trace、Metric相关数据的处理程序例如导出到 Prometheus。其语义要点telemetry.tsstart()是幂等的内部用started标志位保证trace.start()与metric.start()至多执行一次重复调用不会重复创建 Provider启动的具体行为由Trace与Metric各自决定Trace.start() 会按processorName可为逗号分隔的字符串或数组从处理器注册表中取出对应的SpanProcessor工厂并实例化随后创建NodeTracerProvider并调用register()将其设为全局 Tracer ProviderMetric.start() 会按readerName同理实例化MetricReader创建MeterProvider可附带 Views 配置并调用opentelemetry.metrics.setGlobalMeterProvider设为全局 Meter Provider。shutdown()停止数据处理程序shutdown(): Promisevoid停止Trace、Metric相关的数据处理程序。实现上telemetry.ts会并发等待trace.shutdown()与metric.shutdown()完成并将started标志复位。二者分别会遍历所有已激活的SpanProcessor/MetricReader并调用其shutdown()确保缓冲中的 Span 和指标数据被冲刷flush完毕随后关闭NodeTracerProvider/MeterProvider。addInstrumentation()添加插桩工具库addInstrumentation(...instrumentation: InstrumentationOption[])用于添加 OpenTelemetry 的插桩库例如针对 HTTP、Sequelize 等组件的 instrumentation。插件必须在init()之前调用该方法init()内部会把this.instrumentations数组整体交给registerInstrumentations之后追加的插桩不会在当次初始化中生效。在 NocoBase 应用中的集成方式Telemetry并非孤立的类而是被服务端应用Application深度集成。以下结论均可在 application.ts 中验证实例创建应用初始化时会构造Telemetry实例并自动注入appName当前应用名与version从 package.json 读取的当前版本号再展开用户传入的options.telemetry覆盖默认值application.tsthis._telemetry new Telemetry({ appName: this.name, version: this.getPackageVersion(), ...options.telemetry, });选项扩展应用在TelemetryOptions基础上扩展出AppTelemetryOptions新增enabled开关application.tsexport interface AppTelemetryOptions extends TelemetryOptions { enabled?: boolean; }初始化与启动时机遥测的初始化发生在插件beforeLoad钩子之后源码注释明确说明 Telemetry is initialized after beforeLoad hook以便插件在init()前调用addInstrumentation()等 API。init()无条件执行而start()仅在options.telemetry.enabled为真时才触发application.ts// Telemetry is initialized after beforeLoad hook if (!this.telemetry.started) { this.telemetry.init(); if (this.options.telemetry?.enabled) { // Start collecting telemetry data if enabled this.telemetry.start(); } }优雅关闭应用停止时若telemetry.started为真会await this.telemetry.shutdown()保证缓冲数据在进程退出前完成导出application.ts。也就是说默认情况下init()会执行插桩已注册、Resource 已就绪但数据采集Span 导出、Metric 周期读取只有在显式开启telemetry.enabled后才会真正开始这对性能敏感的部署是一个友好的默认行为。默认处理器与读取器console 内置实现Trace和Metric均采用「注册器 名称引用」的设计插件可以通过注册器扩展自定义实现。TraceSpanProcessor 注册表Trace 内部维护一个RegistryGetSpanProcessor构造函数默认注册名为console的处理器this.registerProcessor(console, () new BatchSpanProcessor(new ConsoleSpanExporter()));即默认把 Span 以批量方式打印到控制台。TraceOptions支持tracerName、version、processorName三个配置项其中processorName缺省为console。插件可以调用trace.registerProcessor(name, factory)注册自己的导出器例如指向 Prometheus、OTLP 后端的实现再通过processorName引用多个名称来组合生效未在注册表中找到名称时会被静默跳过trace.ts。启动后插件可通过getTracer(name?, version?)获取 Tracer 创建 Span。MetricMetricReader 注册表与 TELEMETRY_METRICS 过滤Metric 内部维护一个RegistryGetMetricReader默认注册名为console的读取器this.registerReader( console, () new PeriodicExportingMetricReader({ exporter: new ConsoleMetricExporter({ temporalitySelector: () AggregationTemporality.DELTA, }), }), );即默认按周期把指标以 DELTA 时间语义打印到控制台。MetricOptions支持meterName、version、readerName三个配置项readerName缺省为console同样支持逗号分隔的多个名称。一个值得注意的源码细节是指标白名单机制metric.tsstart()会读取环境变量TELEMETRY_METRICS逗号分隔的指标名列表。若该变量非空则生成 OpenTelemetry Views让列出的指标名正常通过并对instrumentName: *的其他所有指标应用AggregationType.DROP聚合——也就是说可以通过TELEMETRY_METRICS环境变量控制只采集指定指标丢弃其余指标用于在生产环境收敛指标基数。小结Telemetry类以constructor → init() → start() → shutdown()的生命周期把 OpenTelemetry 的插桩、链路追踪与指标体系封装进了 NocoBase 的应用生命周期应用创建时构建实例并自动注入appName/versionbeforeLoad之后执行init()注册插桩enabled开启后由start()启动控制台或插件自定义的处理器应用停止时由shutdown()完成数据冲刷。对插件开发者而言扩展路径也很清晰在init()前调用addInstrumentation()添加插桩通过registerProcessor/registerReader注册自定义导出通道并善用TELEMETRY_METRICS环境变量控制指标采集范围。更细粒度的Trace与MetricAPI 可分别参考 Trace 文档 与 Metric 文档。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考