OpenTelemetry 入门

它解决什么

可观测领域曾经是这样的：

用 Datadog → 装 Datadog agent + Datadog SDK
换到 New Relic → 全部重新装
换到自托管 Jaeger → 又一套

应用代码和具体后端绑死。OpenTelemetry（OTel）的目标：应用埋一次点，后端随便换。

OpenTelemetry 是什么

CNCF 项目（2019 年由 OpenCensus + OpenTracing 合并而成），由 Google / Microsoft / 大量厂商共同维护。

定义了一套 API + SDK + 协议（OTLP）
覆盖 Metrics / Traces / Logs 三支柱
多语言 SDK（Java / Go / Python / Node / Rust 等十几种）
后端实现层不归 OTel——你导出到 Jaeger / Tempo / Datadog / 任何兼容 OTLP 的后端

CNCF 内活跃度仅次于 Kubernetes 的项目。事实标准已经形成。

三个组件

应用 (SDK 自动 / 手动埋点)
    ↓ OTLP 协议
Collector（中间网关，可选但强烈推荐）
    ↓ exporter
后端：Jaeger / Tempo / Loki / Prometheus / Datadog / 任意 OTLP 兼容

SDK

应用层一次性接入：

# Python 自动 instrumentation
opentelemetry-instrument python app.py

// Node 自动 instrumentation
require('@opentelemetry/auto-instrumentations-node/register');

会自动给常见库（HTTP / DB / Redis / gRPC）加 traces，应用代码改动近 0。

Collector

应用 1 ─┐
应用 2 ─┼→ Collector ─→ Tempo（traces）
应用 3 ─┘            ─→ Prometheus（metrics）
                     ─→ Loki（logs）

Collector 的好处：

后端切换只改 Collector 配置，不动应用
集中处理：采样 / 过滤 / 富化 / 重试
减少应用对外 SDK 直连

OTLP（OpenTelemetry Protocol）

OTel 自家的传输协议，Protobuf over gRPC（也有 HTTP/JSON 模式）。各大后端都兼容 OTLP——这才让"切换后端"变得真切可行。

自动 vs 手动 instrumentation

	自动	手动
工作量	几乎 0	中-高
覆盖深度	框架边界（HTTP in/out / DB query）	任意业务节点
推荐	起步先用自动	关键业务路径加手动 span

# 手动埋点
from opentelemetry import trace
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("calculate-pricing") as span:
    span.set_attribute("user.id", user_id)
    result = compute(user_id)
    span.set_attribute("pricing.tier", result.tier)

与 Prometheus 的关系

Prometheus 客户端库 vs OTel Metrics SDK 都能写 metrics
Prometheus 兼容 OTLP 协议接收（2024 起）
新项目可以只用 OTel SDK，把所有遥测从一个出口送出去
老项目继续 Prometheus 客户端 + Exporter 模式没问题

与 Jaeger / Zipkin 的关系

Jaeger / Zipkin 是 traces 后端
OTel 取代了 OpenTracing / OpenCensus（这两个项目已经归档）
Jaeger 现在原生支持 OTLP——你用 OTel SDK 写应用，Jaeger 当后端，组合 OK

何时用 OTel

新项目：直接 OTel，别再用厂商专有 SDK
旧项目：渐进迁——先把 Collector 加上，应用层逐步改
单一云 + 单一供应商 + 不打算迁：用云商方案也行，但 OTel 让你有退路

反模式

应用直连后端 + 不走 Collector：换后端就要改应用、加重试逻辑
trace 100% 采样到生产：高 QPS 服务直接打爆 trace 存储；常用做法是头部采样 + 错误强制采或尾部采样
不传 context：没传 W3C Trace Context（HTTP header traceparent），跨服务 trace 链不上