OpenTelemetry JS 自定义导出器开发指南

史琼鸽Power

于 2025-06-19 09:12:40 发布

阅读量365

点赞数 3

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00393/article/details/148755844

OpenTelemetry JS 自定义导出器开发指南

opentelemetry-js OpenTelemetry JavaScript Client 项目地址: https://gitcode.com/gh_mirrors/op/opentelemetry-js

前言

在现代分布式系统中，可观测性已成为系统稳定运行的关键保障。OpenTelemetry 作为新一代的可观测性框架，提供了强大的数据收集能力。本文将深入讲解如何在 OpenTelemetry JS 中开发自定义导出器（Exporter），将遥测数据发送到特定的后端服务。

导出器基础概念

导出器是 OpenTelemetry 架构中的关键组件，负责将收集到的跟踪（Traces）和指标（Metrics）数据发送到后端系统。OpenTelemetry 的核心设计理念之一就是解耦数据收集与数据导出，这使得开发者可以灵活地切换不同的导出器而无需修改应用代码。

导出器项目结构

一个标准的导出器项目通常采用以下目录结构：

opentelemetry-exporter-myexporter
   ├── src
   │   ├── index.ts          # 导出器入口文件
   │   ├── transform.ts      # 数据转换逻辑
   │   ├── types.ts          # 类型定义
   │   ├── my-trace-exporter.ts  # 跟踪数据导出器实现
   │   └── my-metric-exporter.ts # 指标数据导出器实现
   └── test
       ├── transform.test.ts      # 转换逻辑测试
       ├── my-trace-exporter.test.ts  # 跟踪导出器测试
       └── my-metric-exporter.test.ts # 指标导出器测试

跟踪数据导出器开发

SpanExporter 接口规范

跟踪数据导出器需要实现 SpanExporter 接口，该接口定义了导出器必须遵守的契约：

数据接收规则：
- 只接收已被采样的 Span
- 只接收已结束的 Span
- 不得修改接收到的 Span 数据
错误处理规则：
- 禁止抛出异常
- 错误应通过返回值处理
性能考虑：
- 不应自行实现队列或批处理逻辑（这些由 Span 处理器负责）

核心方法实现

export 方法：

export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void

负责将 ReadableSpan 数据转换为后端系统接受的格式并发送。转换过程通常包括：

数据序列化
协议封装
网络传输

shutdown 方法：

shutdown(): Promise<void>

执行资源清理工作，调用后导出器应拒绝后续所有导出请求。

开发建议

参考 Zipkin 或 Jaeger 导出器的实现
在 transform.ts 中集中处理数据转换逻辑
为网络请求添加适当的超时和重试机制

指标数据导出器开发

指标数据导出支持两种模式：推送（Push）和拉取（Pull）。

推送模式导出器

PushMetricExporter 接口

推送模式导出器需要实现 PushMetricExporter 接口：

核心方法：
- export: 处理并发送 ResourceMetrics 数据
- shutdown: 清理资源
- forceFlush: 确保所有待处理数据完成导出
可选配置方法：
- selectAggregationTemporality: 为指标类型选择合适的时间聚合方式
- selectAggregation: 为指标类型选择合适的聚合方式