Skip to content
OpenTelemetry 接入文档

OpenTelemetry 简介

OpenTelemetry 是 CNCF（Cloud Native Computing Foundation）旗下的可观测性项目，旨在为分布式系统提供统一的可观测性标准。它是 OpenTracing 和 OpenCensus 项目合并后的产物，已经成为云原生可观测性的事实标准。

什么是 OpenTelemetry？

OpenTelemetry（简称 OTel）是一组 API、SDK、工具和集成的集合，用于创建和管理遥测数据（traces、metrics 和 logs）。它提供了：

  • 厂商中立的标准：不绑定特定的可观测性后端，可以自由选择数据存储和分析平台
  • 自动化埋点：支持零代码接入，自动捕获应用程序的遥测数据
  • 多语言支持：官方支持 Go、Python、Java、JavaScript、.NET、C++、Erlang、PHP、Ruby、Rust 和 Swift
  • 丰富的集成：提供大量框架和库的自动埋点支持
  • 灵活的配置：通过环境变量和代码配置，满足不同场景需求

为什么使用 OpenTelemetry？

1. 避免厂商锁定

使用 OpenTelemetry 标准协议，您可以轻松切换不同的可观测性后端（如 Jaeger、Zipkin、Prometheus、Uptrace 等），而无需修改应用代码。

2. 降低接入成本

  • 零代码接入：通过 Agent 或自动化工具，无需修改代码即可接入
  • 自动埋点：自动捕获 HTTP、数据库、消息队列等常见组件的调用信息
  • 统一标准：一次接入，支持多种可观测性后端

3. 完整的可观测性

OpenTelemetry 提供三大支柱：

  • Traces（追踪）：记录请求在分布式系统中的完整调用链路
  • Metrics（指标）：采集系统和业务的性能指标
  • Logs（日志）：结构化日志收集，与 Trace 自动关联

4. 生产就绪

OpenTelemetry 已经在大量生产环境中验证，具有：

  • 高性能，低资源开销
  • 稳定的 API 和 SDK
  • 活跃的社区和生态系统
  • 持续的更新和维护

OpenTelemetry 架构

┌─────────────────┐
│  Application    │
│  ┌───────────┐  │
│  │   Code    │  │
│  └─────┬─────┘  │
│        │        │
│  ┌─────▼─────┐  │
│  │ OTel SDK  │  │  ← API + SDK
│  └─────┬─────┘  │
└────────┼────────┘
         │
    ┌────▼────┐
    │ OTLP    │        ← OpenTelemetry Protocol
    └────┬────┘
         │
    ┌────▼────────────┐
    │  OTel Collector │ ← 可选的数据处理层
    └────┬────────────┘
         │
    ┌────▼──────┐
    │  Backend  │      ← APM 平台
    └───────────┘

核心组件

  1. API：定义了创建和管理遥测数据的接口
  2. SDK：API 的实现，负责数据的采集、处理和导出
  3. Instrumentation：自动或手动的代码埋点
  4. Exporter：将数据导出到不同的后端
  5. Collector（可选）：独立的数据收集和处理服务

支持的信号类型

Traces（追踪）

分布式追踪记录请求在系统中的完整调用路径，帮助您：

  • 理解系统的调用关系
  • 定位性能瓶颈
  • 分析故障根因
  • 优化关键路径

示例场景： 一个 HTTP 请求从 API Gateway 开始，经过多个微服务处理，最后返回响应。Trace 会记录每个服务的处理时间、调用关系和错误信息。

Metrics（指标）

指标是关于系统状态的数字测量值，如：

  • 请求速率：每秒处理的请求数
  • 响应时间：请求的处理延迟
  • 错误率：失败请求的比例
  • 系统资源：CPU、内存、网络使用情况

示例场景： 监控 API 端点的 QPS、P99 延迟和错误率，设置告警规则。

Logs（日志）

结构化日志记录应用程序的事件和状态变化：

  • 与 Trace 自动关联
  • 支持结构化字段
  • 统一的日志格式

示例场景： 应用日志自动携带 Trace ID 和 Span ID，可以快速从日志定位到完整的调用链。

接入方式

OpenTelemetry 提供两种主要的接入方式：

1. 零代码接入（推荐）

通过 Agent 或自动化工具，无需修改代码：

语言工具
GoAuto-Instrumentation / loongsuite-go-agent
Pythonopentelemetry-instrument
JavaJava Agent
JavaScript@opentelemetry/auto-instrumentations-node
.NETOpenTelemetry .NET Automatic Instrumentation

优点：

  • 快速接入，5 分钟内完成
  • 无需修改代码
  • 自动支持常见框架和库
  • 统一的配置管理

适用场景：

  • 快速验证和测试
  • 标准的应用架构
  • 希望降低维护成本

2. SDK 手动接入

在代码中显式使用 OpenTelemetry SDK：

优点：

  • 更细粒度的控制
  • 自定义业务埋点
  • 支持复杂场景
  • 可以选择性埋点

适用场景：

  • 需要自定义业务追踪
  • 特殊的框架或库
  • 性能敏感的场景
  • 需要精确控制采样

快速体验

以下是一个 Python 零代码接入的简单示例：

# 1. 安装 OpenTelemetry
pip install opentelemetry-distro opentelemetry-exporter-otlp


# 2. 自动安装埋点库
opentelemetry-bootstrap -a install


# 3. 配置环境变量
export OTEL_SERVICE_NAME=my-service
export OTEL_EXPORTER_OTLP_ENDPOINT=https://your-apm-platform.com
export OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=<your-dsn>


# 4. 启动应用
opentelemetry-instrument python app.py

就这么简单！您的应用现在已经自动埋点并开始发送遥测数据了。

与其他可观测性方案的对比

特性OpenTelemetryPrometheusJaegerELK Stack
Traces✅❌✅❌
Metrics✅✅❌❌
Logs✅❌❌✅
厂商中立✅✅✅⚠️
自动埋点✅❌⚠️❌
多语言支持✅✅✅✅
标准协议✅⚠️⚠️❌

OpenTelemetry 生态系统

OpenTelemetry 拥有丰富的生态系统：

官方支持的语言

  • Go
  • Python
  • Java
  • JavaScript / TypeScript
  • .NET (C#, F#, VB)
  • C++
  • Erlang / Elixir
  • PHP
  • Ruby
  • Rust
  • Swift

支持的后端

  • Jaeger
  • Zipkin
  • Prometheus
  • Grafana Tempo
  • Uptrace
  • New Relic
  • Datadog
  • Honeycomb
  • Lightstep
  • AWS X-Ray
  • Google Cloud Trace
  • Azure Monitor

自动埋点支持的框架（部分）

Web 框架：

  • Go: Gin, Echo, Fiber, Chi, Gorilla Mux
  • Python: Flask, Django, FastAPI, aiohttp, Tornado
  • Java: Spring Boot, Quarkus, Micronaut, Vert.x
  • JavaScript: Express, Koa, NestJS, Next.js, Fastify
  • .NET: ASP.NET Core, Nancy, ServiceStack

数据库：

  • MySQL, PostgreSQL, MongoDB, Redis, Elasticsearch, Cassandra, DynamoDB

消息队列：

  • Kafka, RabbitMQ, RocketMQ, Pulsar, NATS

RPC 框架：

  • gRPC, Dubbo, Thrift, Apache APISIX

版本和稳定性

OpenTelemetry 采用语义化版本控制：

  • API: 稳定版本 (1.0+)，不会有破坏性变更
  • SDK: 稳定版本 (1.0+)，遵循语义化版本
  • Semantic Conventions: 持续演进中
  • Instrumentation: 大部分已稳定

推荐版本

语言最低版本推荐版本状态
Go1.18+1.21+Stable
Python3.7+3.10+Stable
Java8+17+Stable
JavaScriptNode.js 14+Node.js 18+Stable
.NET.NET 6+.NET 8+Stable

性能影响

OpenTelemetry 设计时充分考虑了性能：

  • CPU 开销: < 5%
  • 内存开销: 10-50MB（取决于负载和配置）
  • 网络开销: 可通过采样控制
  • 延迟影响: < 1ms

通过合理的配置（采样率、批量导出等），可以将性能影响降到最低。

下一步

现在您已经了解了 OpenTelemetry 的基础知识，接下来：

  1. 理解核心概念 - 深入了解 Span、Trace、Context 等概念
  2. 配置 DSN - 获取和配置 APM 平台连接凭证
  3. 环境变量配置 - 了解所有可用的配置选项
  4. 选择您的语言开始接入：
  5. Kubernetes 部署（如果使用 Kubernetes）：

参考资源

在Gitlab上编辑本文档