tracegen Docker镜像文档

1. 镜像概述

tracegen 是一款用于生成稳定简单追踪流的工具，主要用于分布式系统的性能调优场景。该工具通过一个或多个工作 goroutine 并发生成追踪数据，支持多种导出格式，可灵活配置目标接收端。

2. 核心功能与特性

• 并发追踪生成：支持多 goroutine 并发生成追踪数据，模拟真实业务场景下的并发追踪负载
• 多导出格式支持：通过 -exporter 标志配置不同的追踪数据导出格式
• 灵活的目标配置：可指定追踪数据的接收端地址，适配容器化环境下的跨容器通信
• OTLP 协议兼容：原生支持 OpenTelemetry Protocol (OTLP) 导出，可通过环境变量配置详细参数
• 轻量容器化：提供 Docker 镜像分发，支持快速部署和集成到现有测试环境

3. 使用场景

• 性能调优测试：生成可控的追踪数据流量，评估分布式追踪系统在不同负载下的性能表现
• 分布式追踪系统验证：测试 Jaeger、OpenTelemetry 等追踪系统的接收、存储和处理能力
• 监控告警阈值校准：模拟不同量级的追踪数据，辅助设置合理的监控告警阈值
• CI/CD 流程集成：在持续集成/部署流程中验证追踪功能的可用性和稳定性

4. 使用方法

4.1 基本使用（Docker Run）

直接通过 docker run 命令启动容器，生成追踪数据：

# 示例：生成 10 条追踪数据，服务名为 "abcd"
docker run jaegertracing/jaeger-tracegen -service abcd -traces 10

4.2 CLI 参数说明

通过 -h 标志查看所有可用命令行参数：

docker run jaegertracing/jaeger-tracegen -h

常用核心参数说明：

4.3 导出器配置

4.3.1 默认行为

• 未指定 -exporter 时，工具使用默认导出方式
• 所有导出器默认将数据发送至 localhost（本地主机）

4.3.2 容器环境下的跨容器导出

在容器中运行时，localhost 指向容器自身的网络命名空间。如需将追踪数据导出到其他容器（如 Jaeger collector 或 OpenTelemetry collector），需通过参数或环境变量显式指定目标地址，例如：

# 示例：导出追踪数据到同一网络中的 Jaeger collector（地址为 jaeger-collector:4317）
docker run --network=trace-network jaegertracing/jaeger-tracegen \
  -service test-service \
  -traces 100 \
  -exporter otlp

4.3.3 OTLP 导出器配置

当使用 -exporter otlp 时，需通过环境变量配置 OTLP 导出参数，遵循 OpenTelemetry 协议规范。常用环境变量：

4.4 Docker Compose 示例

可通过 docker-compose.yml 集成 tracegen 与追踪系统（如 Jaeger），示例配置：

version: '3'
services:
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"  # Jaeger UI
      - "4317:4317"    # OTLP gRPC 接收端口
    environment:
      - COLLECTOR_OTLP_ENABLED=true

  tracegen:
    image: jaegertracing/jaeger-tracegen
    depends_on:
      - jaeger
    environment:
      - OTEL_EXPORTER_OTLP_ENDPOINT=[***]
      - OTEL_EXPORTER_OTLP_PROTOCOL=grpc
    command: ["-service", "demo-service", "-traces", "1000", "-workers", "5", "-exporter", "otlp"]

启动命令：

docker-compose up

5. 配置参数详解

5.1 命令行参数完整列表

5.2 OTLP 导出器环境变量配置