搬瓦工部署 OpenTelemetry 可观测性框架教程

OpenTelemetry（简称 OTel）是 CNCF 的旗舰项目，它提供了一套统一的标准和工具，用于生成、收集和导出遥测数据（追踪、指标和日志）。OpenTelemetry 不是一个后端系统，而是一个框架和协议标准，它的 Collector 组件可以作为遥测数据的中间层，接收来自各种来源的数据并路由到任意后端。本文将介绍如何在搬瓦工 VPS 上部署 OpenTelemetry Collector。部署前请确保已安装 Docker 和 Docker Compose。

一、OpenTelemetry 生态组成

规范（Specification）：定义 API 和 SDK 的标准行为。
SDK：各语言的实现库，用于在应用中生成遥测数据。
Collector：独立的数据收集和处理服务，是部署的核心。
OTLP 协议：OpenTelemetry 原生的数据传输协议。
自动检测：无需修改代码即可为常见框架添加追踪。

二、Collector 架构

OpenTelemetry Collector 采用管道模型，由三个核心组件构成：

Receivers：接收遥测数据，支持 OTLP、Jaeger、Zipkin、Prometheus 等协议。
Processors：处理和转换数据，如批处理、过滤、采样、添加属性等。
Exporters：将数据发送到后端，支持 Jaeger、Zipkin、Prometheus、Loki 等。

三、系统要求

操作系统：Ubuntu 20.04+ 或 Debian 11+。
内存：至少 512MB，推荐 1GB。
磁盘：至少 2GB 可用空间。
Docker：已安装 Docker 和 Docker Compose。

选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享 6.77% 折扣，购买入口：bwh81.net。

四、创建项目目录

mkdir -p /opt/otel-collector && cd /opt/otel-collector

五、编写 Collector 配置文件

cat > /opt/otel-collector/otel-config.yaml <<'EOF'
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: "0.0.0.0:4317"
      http:
        endpoint: "0.0.0.0:4318"

  jaeger:
    protocols:
      thrift_http:
        endpoint: "0.0.0.0:14268"
      grpc:
        endpoint: "0.0.0.0:14250"

  zipkin:
    endpoint: "0.0.0.0:9411"

  prometheus:
    config:
      scrape_configs:
        - job_name: 'otel-collector'
          scrape_interval: 30s
          static_configs:
            - targets: ['localhost:8888']

processors:
  batch:
    timeout: 5s
    send_batch_size: 1024

  memory_limiter:
    check_interval: 1s
    limit_mib: 512
    spike_limit_mib: 128

  attributes:
    actions:
      - key: environment
        value: production
        action: upsert

  filter:
    error_mode: ignore
    traces:
      span:
        - 'attributes["http.target"] == "/health"'

exporters:
  otlp/jaeger:
    endpoint: "jaeger:4317"
    tls:
      insecure: true

  otlp/tempo:
    endpoint: "tempo:4317"
    tls:
      insecure: true

  prometheus:
    endpoint: "0.0.0.0:8889"

  logging:
    verbosity: normal

extensions:
  health_check:
    endpoint: "0.0.0.0:13133"
  zpages:
    endpoint: "0.0.0.0:55679"

service:
  extensions: [health_check, zpages]
  pipelines:
    traces:
      receivers: [otlp, jaeger, zipkin]
      processors: [memory_limiter, batch, attributes]
      exporters: [otlp/jaeger, logging]

    metrics:
      receivers: [otlp, prometheus]
      processors: [memory_limiter, batch]
      exporters: [prometheus, logging]

    logs:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [logging]
EOF

六、编写 Docker Compose 配置

cat > /opt/otel-collector/docker-compose.yml <<'EOF'
version: '3.8'

services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    restart: always
    command: ["--config", "/etc/otel/config.yaml"]
    ports:
      - "4317:4317"   # OTLP gRPC
      - "4318:4318"   # OTLP HTTP
      - "9411:9411"   # Zipkin
      - "14268:14268" # Jaeger HTTP
      - "8889:8889"   # Prometheus metrics
      - "13133:13133" # Health check
      - "55679:55679" # zPages
    volumes:
      - ./otel-config.yaml:/etc/otel/config.yaml:ro
EOF

七、启动服务

cd /opt/otel-collector
docker compose up -d

验证服务状态：

# 健康检查
curl http://localhost:13133/

# 查看 zPages（内部诊断页面）
curl http://localhost:55679/debug/tracez

八、应用接入示例

Python 应用

# pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp

from opentelemetry import trace, metrics
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.sdk.resources import Resource

resource = Resource.create({
    "service.name": "my-app",
    "service.version": "1.0.0",
})

provider = TracerProvider(resource=resource)
exporter = OTLPSpanExporter(endpoint="http://otel-collector:4317", insecure=True)
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

自动检测（零代码接入）

# 安装自动检测工具
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

# 使用自动检测启动应用
OTEL_SERVICE_NAME=my-app \
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317 \
opentelemetry-instrument python app.py

九、常见问题

Collector 内存使用过高

调整 memory_limiter 处理器的参数，减小 limit_mib 值。同时检查是否有数据风暴导致接收量过大。

数据未到达后端

查看 Collector 日志和 zPages 诊断页面，确认 Pipeline 配置正确且后端可达。

总结

OpenTelemetry Collector 是可观测性基础设施的核心中间层，它提供了厂商无关的数据收集和路由能力。通过 Collector，你可以自由切换后端系统而无需修改应用代码。配合 Jaeger、Tempo 或 SigNoz 使用效果更佳。选购搬瓦工 VPS 使用优惠码 NODESEEK2026 可享 6.77% 折扣。