## 前言

监控的三大支柱：指标（Metrics）、日志（Logs）、追踪（Traces）。Prometheus 解决了指标问题，但微服务调用链路的问题需要分布式追踪。本篇讲解如何用 OpenTelemetry + Jaeger 补齐追踪维度。

---

## 一、可观测性三大支柱

```
┌─────────────────────────────────────────────┐
│              可观测性 Observability           │
├───────────┬───────────┬─────────────────────┤
│  Metrics  │   Logs    │     Traces          │
│  指标      │  日志      │     追踪            │
│           │           │                     │
│  发生了什么│  具体细节  │  调用链路            │
│  何时发生  │  为什么    │  从哪来到哪去         │
│           │           │                     │
│ Prometheus│  ELK/Loki │  Jaeger/Tempo       │
│           │           │                     │
│  数值趋势  │  文本记录  │  请求路径             │
└───────────┴───────────┴─────────────────────┘

三者的关系：
  指标告诉你"有问题" → 追踪告诉你"在哪条链路" → 日志告诉你"具体什么错"
```

---

## 二、分布式追踪核心概念

### Trace 和 Span

```
Trace（追踪）= 一个完整的请求链路

  User Request
      │
      ├── Span: Gateway (50ms)
      │       ├── Span: Auth Service (10ms)
      │       ├── Span: Order Service (30ms)
      │       │       ├── Span: Inventory Service (15ms)
      │       │       └── Span: Payment Service (10ms)
      │       └── Span: Notification Service (5ms)
      │
      Total: 50ms

Span = 链路中的一个操作
  - Operation Name: 操作名称
  - Start Time: 开始时间
  - Duration: 持续时间
  - Tags: 标签（如 http.method, http.status_code）
  - Logs: 事件日志
  - SpanContext: TraceID + SpanID
  - References: 父子关系
```

### 调用关系

```
Trace 树形结构：

  [Root Span] Gateway
       │
       ├──[Child Span] Auth Service
       │
       ├──[Child Span] Order Service
       │       │
       │       ├──[Child Span] Inventory
       │       │
       │       └──[Child Span] Payment
       │
       └──[Child Span] Notification
```

---

## 三、OpenTelemetry

### 什么是 OpenTelemetry

```
OpenTelemetry (OTel) = CNCF 的可观测性标准

  - 统一的数据格式（OTLP）
  - 统一的 API 和 SDK
  - 支持多种后端（Jaeger/Tempo/Zipkin/Prometheus）
  - 支持多种语言（Java/Go/Python/Node/.NET/Rust）
  - 自动埋点 + 手动埋点
```

### 架构

```
应用代码
  ├── OTel SDK（自动埋点）
  │   ├── HTTP 请求自动追踪
  │   ├── 数据库调用自动追踪
  │   ├── 消息队列自动追踪
  │   └── gRPC 调用自动追踪
  │
  └── OTel API（手动埋点）
      └── 自定义 Span

  → OTLP 协议
  → OTel Collector（可选，中转/处理）
  → Jaeger / Tempo / Prometheus
```

---

## 四、Python 应用接入

### 安装

```bash
pip install opentelemetry-api \
            opentelemetry-sdk \
            opentelemetry-exporter-otlp \
            opentelemetry-instrumentation-flask \
            opentelemetry-instrumentation-requests \
            opentelemetry-instrumentation-psycopg2
```

### 自动埋点

```python
# app.py
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.instrumentation.requests import RequestsInstrumentor
from flask import Flask, jsonify
import requests

# 初始化 Tracing
trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)

# 配置 OTLP 导出器
otlp_exporter = OTLPSpanExporter(
    endpoint="http://otel-collector:4317",
    insecure=True
)
span_processor = BatchSpanProcessor(otlp_exporter)
trace.get_tracer_provider().add_span_processor(span_processor)

app = Flask(__name__)

# 自动埋点 Flask
FlaskInstrumentor().instrument_app(app)

# 自动埋点 requests
RequestsInstrumentor().instrument()

@app.route('/api/orders/<order_id>')
def get_order(order_id):
    # 自动创建 Span
    with tracer.start_as_current_span("get_order") as span:
        span.set_attribute("order.id", order_id)
        
        # 调用其他服务（自动传播 trace context）
        resp = requests.get(f"http://inventory:8080/api/inventory/{order_id}")
        inventory = resp.json()
        
        span.set_attribute("inventory.status", inventory.get('status', 'unknown'))
        
        return jsonify({"order_id": order_id, "inventory": inventory})

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080)
```

### 手动埋点

```python
from opentelemetry import trace

tracer = trace.get_tracer(__name__)

def process_payment(order_id, amount):
    with tracer.start_as_current_span("process_payment") as span:
        # 设置属性
        span.set_attribute("payment.order_id", order_id)
        span.set_attribute("payment.amount", amount)
        
        try:
            # 业务逻辑
            result = charge_card(amount)
            
            # 添加事件
            span.add_event("payment_charged", {
                "transaction_id": result.txn_id
            })
            
            return result
        except Exception as e:
            # 记录错误
            span.record_exception(e)
            span.set_status(trace.Status(trace.StatusCode.ERROR, str(e)))
            raise

def charge_card(amount):
    with tracer.start_as_current_span("charge_card") as span:
        span.set_attribute("card.amount", amount)
        # 模拟调用
        time.sleep(0.1)
        return Transaction(txn_id="txn_123", amount=amount)
```

---

## 五、OTel Collector

### 部署

```yaml
# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 5s
    send_batch_size: 1000
  
  # 采样
  probabilistic_sampler:
    sampling_percentage: 50    # 50% 采样
  
  # 过滤
  filter:
    traces:
      span:
        - 'attributes.http.status_code == 404'    # 过滤 404

exporters:
  # 发送到 Jaeger
  jaeger:
    endpoint: jaeger:14250
    tls:
      insecure: true
  
  # 发送到 Tempo
  otlp/tempo:
    endpoint: tempo:4317
    tls:
      insecure: true
  
  # 同时发送指标到 Prometheus
  prometheus:
    endpoint: 0.0.0.0:8889
  
  # 发送到日志系统
  loki:
    endpoint: http://loki:3100/loki/api/v1/push

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [probabilistic_sampler, filter, batch]
      exporters: [jaeger]
    
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]
    
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [loki]
```

### Docker 部署

```yaml
# docker-compose.yml
services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.96.0
    command: ["--config=/etc/otelcol/config.yaml"]
    volumes:
      - ./otel-collector-config.yaml:/etc/otelcol/config.yaml
    ports:
      - "4317:4317"   # OTLP gRPC
      - "4318:4318"   # OTLP HTTP
      - "8889:8889"   # Prometheus exporter
```

---

## 六、Jaeger 部署

### Docker

```bash
# All-in-one（开发环境）
docker run -d \
  --name jaeger \
  -p 16686:16686 \
  -p 14250:14250 \
  -p 4317:4317 \
  -p 4318:4318 \
  jaegertracing/all-in-one:1.55

# 访问 Web UI
# http://localhost:16686
```

### 生产部署

```yaml
# docker-compose.yml
services:
  jaeger:
    image: jaegertracing/all-in-one:1.55
    environment:
      - COLLECTOR_OTLP_ENABLED=true
      - SPAN_STORAGE_TYPE=elasticsearch
      - ES_SERVER_URL=http://elasticsearch:9200
      - ES_TAGS_AS_FIELDS_ALL=true
    ports:
      - "16686:16686"    # Web UI
      - "4317:4317"      # OTLP gRPC
      - "4318:4318"      # OTLP HTTP
      - "14250:14250"    # Jaeger gRPC
      - "14268:14268"    # Jaeger HTTP
```

### Kubernetes

```bash
# Jaeger Operator
kubectl create namespace observability
kubectl apply -f https://github.com/jaegertracing/jaeger-operator/releases/download/v1.55.0/jaeger-operator.yaml

# 创建 Jaeger 实例
cat <<EOF | kubectl apply -f -
apiVersion: jaegertracing.io/v1
kind: Jaeger
metadata:
  name: jaeger
  namespace: observability
spec:
  strategy: production
  storage:
    type: elasticsearch
    options:
      es:
        server-urls: http://elasticsearch:9200
  ingress:
    enabled: true
    hosts:
      - jaeger.example.com
EOF
```

---

## 七、关联 Prometheus 指标与追踪

### Exemplar（示例）

```yaml
# Prometheus 配置启用 Exemplar
scrape_configs:
  - job_name: 'otel-collector'
    static_configs:
      - targets: ['otel-collector:8889']
    # 自动支持 exemplar
```

```python
# 在指标中嵌入 trace_id
from opentelemetry import trace
from prometheus_client import Counter

requests_total = Counter('http_requests_total', 'Total requests', ['method'])

def handle_request(method):
    span = trace.get_current_span()
    ctx = span.get_span_context()
    
    # 指标 + Exemplar（trace_id）
    requests_total.labels(method=method).inc(
        exemplar={'trace_id': f'{ctx.trace_id:032x}'}
    )
```

```promql
# 在 Grafana 中查看指标时，点击数据点可以跳转到 Jaeger 对应的 trace
# 需要 Grafana 配置 Jaeger 数据源
```

### Grafana 关联

```yaml
# Grafana 数据源
datasources:
  - name: Jaeger
    type: jaeger
    url: http://jaeger:16686
  
  - name: Prometheus
    type: prometheus
    url: http://prometheus:9090
    jsonData:
      exemplarTraceIdDestinations:
        - name: trace_id
          datasourceUid: jaeger
```

```
Grafana 中使用：
  1. Prometheus 面板配置 Data links → URL: /d/jaeger?var-trace_id=${__field.labels.trace_id}
  2. 点击指标数据点 → 跳转到 Jaeger 对应 trace
```

---

## 八、采样策略

### 采样类型

```
1. Head Sampling（头部采样）
   - 在应用入口决定是否采样
   - 简单，但可能丢失关键 trace
   - OTel SDK probabilistic sampler

2. Tail Sampling（尾部采样）
   - 在 Collector 端看到完整 trace 后决定
   - 可以根据错误/延迟智能采样
   - 更精准，但需要缓冲
```

### 尾部采样配置

```yaml
processors:
  tail_sampling:
    decision_wait: 30s         # 等待完整 trace
    num_traces: 50000          # 缓冲的 trace 数
    policies:
      # 采样所有错误
      - name: errors
        type: status_code
        status_code:
          status_codes: [ERROR]
      
      # 采样慢请求
      - name: slow
        type: latency
        latency:
          threshold_ms: 500
      
      # 10% 随机采样
      - name: random
        type: probabilistic
        probabilistic:
          sampling_percentage: 10
```

---

## 要点回顾

| 组件 | 作用 |
|------|------|
| OpenTelemetry SDK | 应用埋点（自动+手动） |
| OTel Collector | 数据中转/处理/采样 |
| Jaeger | 追踪存储和查询 |
| Exemplar | 指标→追踪关联 |
| Tail Sampling | 智能采样 |

- 可观测性三支柱：Metrics + Logs + Traces
- OpenTelemetry 是统一标准，支持多语言多后端
- 自动埋点覆盖 HTTP/DB/MQ/gRPC
- OTel Collector 做中转、采样、过滤
- Exemplar 实现指标到追踪的跳转
- 尾部采样比头部采样更精准

---

## 下一篇预告

追踪搞定了，下一篇 **【Prometheus·进阶篇】监控实战：微服务指标埋点与 SLI/SLO 落地** 将讲解如何用指标定义服务等级目标。

监控的三大支柱：指标（Metrics）、日志（Logs）、追踪（Traces）。Prometheus 解决了指标问题，但微服务调用链路的问题需要分布式追踪。本篇讲解如何用 OpenTelemetry + Jaeger 补齐追踪维度。

【Prometheus·进阶篇】分布式追踪：OpenTelemetry 与 Jaeger 集成

研发部经理

人工智能

本文讲解OpenTelemetry+Jaeger补齐微服务追踪维度，涵盖Trace/Span核心概念、Python自动与手动埋点、OTelCollector部署、Jaeger生产配置、Exemplar关联Prometheus指标跳转追踪，以及Head/Tail采样策略，构建完整可观测性体系。

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【Prometheus·进阶篇】分布式追踪：OpenTelemetry 与 Jaeger 集成-腾讯云开发者社区-腾讯云

【Prometheus·进阶篇】分布式追踪：OpenTelemetry 与 Jaeger 集成

【Prometheus·进阶篇】分布式追踪：OpenTelemetry 与 Jaeger 集成

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐