跳转至

OpenTelemetry

OpenTelemetry 是一套用于生成、采集和传输 Trace、Metric、Log 等遥测数据的开放标准。通过 OpenTelemetry，可以使用统一的数据模型和 OTLP 协议观测不同语言、框架及运行环境中的应用。

OpenTelemetry 生态支持

观测云已被收录于 OpenTelemetry 官方 Vendors 名单。根据官方标注，观测云是商业可观测性厂商，并支持 Native OTLP，可原生接收 OpenTelemetry 遥测数据。通过观测云，用户可以统一查看和分析 OpenTelemetry 产生的 Trace、Metric 和 Log 数据，并结合基础设施、应用性能及用户访问等数据进行关联分析。

本文档介绍如何将应用的 OpenTelemetry 数据发送到 DataKit，再由 DataKit 上报到观测云：

应用 + OpenTelemetry 插桩 -> OTLP -> DataKit -> 观测云

选择接入方式

根据语言生态和应用改造要求，选择 Zero-code Instrumentation 或 SDK Instrumentation：

接入方式 适用语言 工作方式 适用场景
Zero-code Instrumentation Java、Python、PHP、Node.js、.NET、Go 通过 Agent、运行时 Hook、扩展、启动参数或编译期插桩为受支持的框架和组件自动创建遥测数据。 希望尽量少修改业务代码，快速采集常见 Web、HTTP、数据库和消息队列调用。
SDK Instrumentation Go 在应用中初始化 OpenTelemetry SDK，并使用框架插桩库或 API 创建遥测数据。 需要显式控制 Provider、Exporter、采样、资源属性和业务 Span。

Zero-code 表示无需修改或只需极少修改业务逻辑，并不代表无需安装组件、配置上报参数或重启应用。自动插桩只覆盖受支持的框架和组件；业务内部的重要操作仍可通过 OpenTelemetry API 补充自定义 Span、Metric 和属性。

Zero-code Instrumentation

语言 插桩方式 接入文档
Java 通过 JVM -javaagent 加载 OpenTelemetry Java Agent。 OpenTelemetry Java；Java 扩展
Python 通过 opentelemetry-instrument 启动应用并加载对应插桩包。 OpenTelemetry Python
PHP 通过 OpenTelemetry PHP 扩展提供运行时 Hook，并由 Composer 插桩包采集框架调用。 OpenTelemetry PHP
Node.js 通过 NODE_OPTIONS 预加载 OpenTelemetry 自动插桩模块。 OpenTelemetry Node.js
.NET 通过 CLR Profiler 和 Startup Hook 加载 OpenTelemetry .NET Automatic Instrumentation。 OpenTelemetry .NET
Go 通过 LoongSuite 在 go build 编译期间注入 OpenTelemetry SDK 和插桩逻辑。 OpenTelemetry Go（LoongSuite）

SDK Instrumentation

语言 插桩方式 接入文档
Go 初始化 OpenTelemetry Go SDK、OTLP Exporter 和上下文传播器，并为使用到的框架或组件安装插桩库。 OpenTelemetry Go SDK

接入流程

不同语言的具体安装命令和启动参数不同，但整体接入流程一致：

  1. 开启 DataKit OpenTelemetry 采集器：配置 OTLP/HTTP 或 OTLP/gRPC 接收端点，重启 DataKit 并确认网络可达；
  2. 为应用启用 OpenTelemetry 插桩：根据语言安装 Agent、扩展、自动插桩模块或 SDK；
  3. 配置数据上报参数：设置服务名、资源属性、OTLP 协议、DataKit 地址、采样及信号开关；
  4. 重启并访问应用：产生真实请求，触发 Trace 和 Metric 数据；
  5. 验证数据：在观测云中检查服务、链路和指标，并结合应用及 DataKit 日志排查上报错误。

DataKit OTLP 接收地址

本文档中的主机接入示例使用以下地址。<DataKit-IP> 应替换为应用能够访问的 DataKit 地址：

协议 信号 接收地址
OTLP/HTTP + Protobuf Trace http://<DataKit-IP>:9529/otel/v1/traces
OTLP/HTTP + Protobuf Metric http://<DataKit-IP>:9529/otel/v1/metrics
OTLP/HTTP + Protobuf Log http://<DataKit-IP>:9529/otel/v1/logs
OTLP/gRPC Trace、Metric、Log http://<DataKit-IP>:4317

使用通用 OTLP/HTTP 基础地址时，可以配置为：

export OTEL_EXPORTER_OTLP_ENDPOINT="http://<DataKit-IP>:9529/otel"

支持标准 OTLP 环境变量的 Exporter 会按信号自动追加 /v1/traces、/v1/metrics 或 /v1/logs。如果使用信号专用地址，例如 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT，则需要填写包含 /otel/v1/traces 的完整地址。

OTLP/gRPC 地址不能追加 /v1/traces 等 HTTP 路径。应用和 DataKit 不在同一主机时，还需要调整 DataKit 监听地址、防火墙或其他网络访问控制。不要将 OTLP 接收端口直接暴露到公网。

完整的 DataKit 参数说明参见 OpenTelemetry 采集器。

统一参数建议

无论使用哪种语言，建议统一规划以下资源属性和传播参数：

参数或属性 作用 建议
service.name 标识服务，是 APM 服务归属的核心字段。 使用稳定且唯一的服务名，不要使用 Pod、进程 ID 等动态值。
deployment.environment.name 标识部署环境。 统一使用 dev、test、staging、prod 等约定值。
service.version 标识应用版本。 使用发布版本、构建版本或 Commit ID，便于比较不同版本的性能。
OTEL_RESOURCE_ATTRIBUTES 批量设置资源属性。 只放置低基数且不包含敏感信息的属性。
OTEL_PROPAGATORS 控制跨服务上下文传播格式。 默认优先使用 tracecontext,baggage，调用链上的服务保持兼容。
采样策略 控制采集量和开销。 接入验证阶段可全采样；生产环境根据流量、存储和排障需求调整。

自定义资源属性如需在观测云中作为标签保留，应加入 DataKit customer_tags 白名单。属性名中的 . 会转换为 _，例如 team.name 转换为 team_name。

验证数据

接入完成后，先访问应用接口产生请求，再进行以下检查：

  1. 执行 curl http://<DataKit-IP>:9529/v1/ping，确认应用可以访问 DataKit；
  2. 检查应用启动日志，确认 Agent、扩展或 SDK 已加载，且没有 OTLP Exporter 报错；
  3. 在观测云的应用性能监测中按 service.name 查询服务和链路；
  4. Metric 通常按周期导出，需等待至少一个导出周期后再查询；
  5. 查询不到数据时，依次检查 DataKit 采集器配置、应用到 DataKit 的网络、OTLP 协议和上报地址。

文档评价

文档内容是否对您有帮助？ ×