jaegertracing/jaeger-debug-snapshot

Jaeger V2 (实验性，基于OpenTelemetry Collector) 镜像文档

1. 镜像概述和主要用途

1.1 概述

本镜像是基于OpenTelemetry Collector构建的实验性Jaeger V2版本，整合了Jaeger分布式追踪系统与OpenTelemetry的可观测性数据处理能力。Jaeger是开源端到端分布式追踪系统，而OpenTelemetry Collector提供灵活的数据收集、处理和导出架构，两者结合旨在提供下一代追踪解决方案的实验性预览。

1.2 主要用途

用于分布式系统中追踪数据的全生命周期管理，包括收集、处理、存储和可视化，支持微服务架构下的性能监控、请求链路追踪及问题根因分析。

2. 核心功能和特性

• OpenTelemetry Collector架构：采用可插拔组件设计，支持灵活配置接收者（Receivers）、处理器（Processors）和导出者（Exporters）
• 实验性Jaeger V2特性：包含Jaeger V2预览功能，可能涉及性能优化、存储后端扩展及协议兼容性增强（具体以镜像版本为准）
• 多协议兼容：支持OpenTelemetry协议（OTLP/gRPC、OTLP/HTTP）、Jaeger Thrift协议等多种数据输入格式
• 多后端集成：可导出数据至Elasticsearch、Cassandra、Prometheus等存储系统及可视化平台
• OpenTelemetry生态融合：无缝对接OpenTelemetry可观测性工具链，支持与 metrics、logs 数据联动分析
• 轻量级容器化设计：优化资源占用，适配Kubernetes等容器编排环境

3. 使用场景和适用范围

3.1 适用场景

• 分布式系统追踪数据的实时采集与分析
• 微服务架构下的请求链路可视化与性能瓶颈定位
• 统一可观测性平台中的追踪数据处理节点
• 实验环境中评估Jaeger V2新特性与性能表现

3.2 适用范围

• 开发、测试及实验性环境（不建议用于生产环境）
• 基于容器化部署的微服务架构
• 需要统一处理多来源追踪数据的技术栈
• OpenTelemetry协议兼容的可观测性体系

4. 使用方法和配置说明

4.1 快速启动（Docker Run）

docker
docker run -d \
  --name jaeger-v2-otelcol \
  -p 16686:16686 \  # Jaeger UI查询端口
  -p 4317:4317 \    # OTLP/gRPC接收端口
  -p 4318:4318 \    # OTLP/HTTP接收端口
  -p 14268:14268 \  # Jaeger Thrift HTTP接收端口
  -v $(pwd)/otelcol-config.yaml:/etc/otelcol/otelcol-config.yaml:ro \
  -e LOG_LEVEL=debug \
  jaegertracing/jaeger-v2-otelcol:latest

4.2 Docker Compose配置

yaml
version: '3.8'
services:
  jaeger-v2:
    image: jaegertracing/jaeger-v2-otelcol:latest
    container_name: jaeger-v2-otelcol
    ports:
      - "16686:16686"  # UI端口
      - "4317:4317"    # OTLP gRPC
      - "4318:4318"    # OTLP HTTP
      - "14268:14268"  # Jaeger Thrift HTTP
    volumes:
      - ./otelcol-config.yaml:/etc/otelcol/otelcol-config.yaml:ro  # 自定义配置文件
      - jaeger-data:/var/lib/jaeger  # 持久化存储（如启用）
    environment:
      - LOG_LEVEL=info
      - JAEGER_STORAGE_TYPE=elasticsearch  # 示例：使用Elasticsearch存储
      - ES_ENDPOINT=http://elasticsearch:9200
    restart: unless-stopped
    depends_on:
      - elasticsearch  # 如需外部存储，需配置依赖服务

  elasticsearch:  # 示例存储后端（可选）
    image: docker.elastic.co/elasticsearch/elasticsearch:8.10.4
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
    ports:
      - "9200:9200"
    volumes:
      - es-data:/usr/share/elasticsearch/data

volumes:
  jaeger-data:
  es-data:

4. 使用配置详解

4.1 环境变量说明

4.2 核心配置文件说明

OpenTelemetry Collector通过otelcol-config.yaml定义数据处理流程，基础配置示例如下：

yaml
receivers:
  # 数据接收组件配置
  otlp:
    protocols:
      grpc:  # 监听4317端口（OTLP/gRPC）
      http:  # 监听4318端口（OTLP/HTTP）
  jaeger:
    protocols:
      thrift_http:  # 监听14268端口（Jaeger Thrift HTTP）

processors:
  # 数据处理组件配置
  batch:  # 批量处理优化（默认启用）
    timeout: 5s
    send_batch_size: 1024
  memory_limiter:  # 内存限制（防止OOM）
    limit_mib: 512
    spike_limit_mib: 128
    check_interval: 5s

exporters:
  # 数据导出组件配置
  jaeger:  # 导出至Jaeger存储（实验性V2）
    endpoint: "localhost:14250"
    tls:
      insecure: true
  logging:  # 日志输出（调试用）
    loglevel: debug

service:
  # 定义数据处理管道
  pipelines:
    traces:
      receivers: [otlp, jaeger]  # 启用的接收者
      processors: [memory_limiter, batch]  # 启用的处理器
      exporters: [jaeger, logging]  # 启用的导出者

4.3 端口映射说明

5. 注意事项

• 实验性声明：本镜像为Jaeger V2实验版本，功能稳定性未经验证，严禁用于生产环境
• 存储配置：默认使用内存存储（重启后数据丢失），持久化需配置JAEGER_STORAGE_TYPE及对应后端连接参数
• 资源要求：建议分配至少1GB内存（通过--memory=1g限制），高流量场景需增加CPU/内存配置
• 配置自定义：复杂场景需通过挂载otelcol-config.yaml覆盖默认配置，推荐使用ConfigMap管理配置（K8s环境）
• 版本兼容性：需确认客户端SDK与Jaeger V2协议兼容性（参考OpenTelemetry文档）