使用 telemetrygen 生成合成 OpenTelemetry 数据

使用 telemetrygen 向 ClickStack OpenTelemetry collector 发送多样化的合成日志、链路追踪和指标

telemetrygen 是 OpenTelemetry Collector Contrib 提供的数据生成器。它会生成合成的 OTLP 日志、链路追踪和指标，并提供可用于控制数据形态的命令行参数，例如多个服务、日志级别、span 状态和子 span，以及不同的指标类型。你可以用它来确认 ClickStack OpenTelemetry collector 是否正在接收数据，以及多样化且逼真的事件是否会出现在 ClickStack UI 中。

本指南假定 collector 已在 4317 (gRPC) 和 4318 (HTTP) 上开放 OTLP 端点，并且正在运行。

托管 ClickStack

1. 前置条件

   本指南假定你已完成托管 ClickStack 入门指南，并且已有一个正在运行的 OpenTelemetry Collector，其 OTLP gRPC (4317) 和 HTTP (4318) 端点可从运行 telemetrygen 的机器访问。如果你已使用 OTLP_AUTH_TOKEN 保护该 Collector，请将该值妥善保存备用。

2. 安装 telemetrygen

   直接通过它的 Docker 镜像运行 telemetrygen (无需安装) 。定义一个简单的包装命令，方便保持下面的命令简洁易读；--add-host 可让容器访问监听在主机上的 collector：

   telemetrygen() {
     docker run --rm --add-host=host.docker.internal:host-gateway \
       ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:latest "$@"
   }
   export OTEL_ENDPOINT=host.docker.internal:4317
   

   或者使用 Go 安装该二进制文件，并将目标设为 localhost：

   go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
   export OTEL_ENDPOINT=localhost:4317
   
3. 设置环境变量

   如果 collector 已启用安全机制，请导出认证令牌：

   export OTLP_AUTH_TOKEN=<your_otlp_auth_token>
   

   未受保护的 collector

   ClickStack OpenTelemetry collector 默认不启用身份验证。如果你尚未按照保护 collector中的说明设置 OTLP_AUTH_TOKEN，请从下面的辅助命令中删除 --otlp-header 这一行。

   定义一个简洁的 tg 辅助函数，这样每条命令只需指定会变化的部分 (service、severity、status、属性) ：

   tg() { local signal=$1; shift; telemetrygen "$signal" \
     --otlp-endpoint ${OTEL_ENDPOINT} --otlp-insecure \
     --otlp-header "authorization=\"${OTLP_AUTH_TOKEN}\"" \
     --rate 5 --duration 30s "$@"; }
   
4. 生成日志

   发送跨服务、贴近真实的不同严重级别日志：以信息级为主，夹杂少量警告和错误，而不是单一均匀的日志流：

   tg logs --service frontend --severity-text Info  --severity-number 9  --body "GET /api/products 200" \
     --otlp-attributes 'deployment.environment="production"' \
     --telemetry-attributes 'http.method="GET"' --telemetry-attributes 'http.status_code="200"'
   tg logs --service checkout --severity-text Warn  --severity-number 13 --body "retrying payment authorization" \
     --otlp-attributes 'deployment.environment="production"' \
     --telemetry-attributes 'http.method="POST"'
   tg logs --service payment  --severity-text Error --severity-number 17 --body "payment gateway timeout" \
     --otlp-attributes 'deployment.environment="production"' \
     --telemetry-attributes 'http.status_code="500"'
   

   最有用的日志参数：

   • --service 设置 service.name，以便将事件归因到某个服务。
   • --severity-text 和 --severity-number 设置级别 (severity-number 的取值范围为 1 到 24) 。
   • --body 设置日志消息。
   • --otlp-attributes 设置资源级属性 (key="value"、key=true 或 key=<integer>) 。
   • --telemetry-attributes 设置每条记录的属性。
5. 生成链路追踪

   发送来自多个健康服务和一个故障依赖项的多 span 链路追踪。这样可以让服务地图呈现更贴近真实的形态：大多数服务健康，只有一个服务报错，并填充错误相关视图：

   # Healthy services: the bulk of the traffic, all spans Ok
   for svc in frontend checkout cart; do
     tg traces --service "$svc" --child-spans 3 --span-duration 80ms --status-code Ok \
       --otlp-attributes 'deployment.environment="production"' \
       --telemetry-attributes "http.route=\"/$svc\""
   done
   
   # One slow dependency returning errors
   tg traces --service payment --child-spans 3 --span-duration 450ms --span-links 1 --status-code Error \
     --otlp-attributes 'deployment.environment="production"' \
     --telemetry-attributes 'http.route="/charge"'
   

   最有用的 trace 标志：

   • --child-spans 为每个 trace 生成指定数量的子 span，让每个 trace 具有更真实的层次深度。
   • --span-duration 设置每个 span 的持续耗时 (例如 120ms、2s) 。
   • --status-code 可设为 Unset、Error、Ok (或 0、1、2) 。使用 Error 可触发 error 视图。
   • --span-links 在 span 之间添加链接。
   • --workers 并行运行多个生成器，以产生更高、更多样的流量。
6. 生成指标

   发送三种常见的指标类型，让仪表盘中显示计数器、Gauge 和分布。与某些生成器不同，telemetrygen 在生成指标时会遵循 --duration 设置，因此无需手动停止：

   tg metrics --service frontend --metric-type Sum       --otlp-metric-name http.server.requests --aggregation-temporality cumulative
   tg metrics --service frontend --metric-type Gauge     --otlp-metric-name system.memory.usage
   tg metrics --service payment  --metric-type Histogram --otlp-metric-name http.server.duration
   

   --metric-type 可接受 Gauge、Sum、Histogram 或 ExponentialHistogram。--otlp-metric-name 用于为该序列命名，便于你在 UI 中找到它；--aggregation-temporality 则可设为 delta 或 cumulative。

7. 在 ClickStack 中验证

   从 ClickHouse Cloud 控制台打开 ClickStack UI。在 Search 视图中，将时间范围设置为 Last 15 minutes，然后在 Logs 和 Traces 数据源之间切换。按 ServiceName 过滤，可查看 frontend、checkout、cart 和 payment 服务；按 SeverityText 过滤，可查找警告和错误日志。打开一条 payment trace，查看其子 span 和错误状态。打开 Chart Explorer，选择 Metrics，并将你在上面设置的某个指标名称绘制成图表 (例如 http.server.requests) ，以验证指标摄取。

ClickStack 开源版

1. 前置条件

   本指南假定你已按照一体化镜像说明启动开源 ClickStack，并且 OTLP 端点 (4317 gRPC 和 4318 HTTP) 可访问。你还需要从 HyperDX UI 的 Team Settings > API Keys 获取摄取 API key。

2. 安装 telemetrygen

   直接通过其 Docker 镜像运行 telemetrygen (无需安装) 。定义一个简单的封装，这样下面的命令会更易读；--add-host 让容器能够连接到监听在宿主机上的 collector：

   telemetrygen() {
     docker run --rm --add-host=host.docker.internal:host-gateway \
       ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:latest "$@"
   }
   export OTEL_ENDPOINT=host.docker.internal:4317
   

   或者使用 Go 安装该二进制程序，并将目标设为 localhost：

   go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
   export OTEL_ENDPOINT=localhost:4317
   
3. 设置环境变量

   导出摄取 API key：

   export CLICKSTACK_API_KEY=<your_ingestion_api_key>
   

   定义一个小型 tg 辅助函数，这样每条命令只需指定会变化的部分 (服务、严重级别、status、属性) ：

   tg() { local signal=$1; shift; telemetrygen "$signal" \
     --otlp-endpoint ${OTEL_ENDPOINT} --otlp-insecure \
     --otlp-header "authorization=\"${CLICKSTACK_API_KEY}\"" \
     --rate 5 --duration 30s "$@"; }
   
4. 生成日志

   以符合实际的方式向多个服务发送不同严重级别的日志：以信息级日志为主，夹杂少量警告和错误，而不是单一、均匀的日志流：

   tg logs --service frontend --severity-text Info  --severity-number 9  --body "GET /api/products 200" \
     --otlp-attributes 'deployment.environment="production"' \
     --telemetry-attributes 'http.method="GET"' --telemetry-attributes 'http.status_code="200"'
   tg logs --service checkout --severity-text Warn  --severity-number 13 --body "retrying payment authorization" \
     --otlp-attributes 'deployment.environment="production"' \
     --telemetry-attributes 'http.method="POST"'
   tg logs --service payment  --severity-text Error --severity-number 17 --body "payment gateway timeout" \
     --otlp-attributes 'deployment.environment="production"' \
     --telemetry-attributes 'http.status_code="500"'
   
5. 生成链路追踪

   从多个健康服务以及一个故障依赖项发送包含多个 span 的链路追踪。这样可以让服务地图呈现更贴近实际的形态——大多数服务健康，只有一个服务报错——并让错误视图中也有数据：

   # Healthy services: the bulk of the traffic, all spans Ok
   for svc in frontend checkout cart; do
     tg traces --service "$svc" --child-spans 3 --span-duration 80ms --status-code Ok \
       --otlp-attributes 'deployment.environment="production"' \
       --telemetry-attributes "http.route=\"/$svc\""
   done
   
   # One slow dependency returning errors
   tg traces --service payment --child-spans 3 --span-duration 450ms --span-links 1 --status-code Error \
     --otlp-attributes 'deployment.environment="production"' \
     --telemetry-attributes 'http.route="/charge"'
   
6. 生成指标

   发送三种常见的指标类型，以便图表中包含计数器、仪表和分布：

   tg metrics --service frontend --metric-type Sum       --otlp-metric-name http.server.requests --aggregation-temporality cumulative
   tg metrics --service frontend --metric-type Gauge     --otlp-metric-name system.memory.usage
   tg metrics --service payment  --metric-type Histogram --otlp-metric-name http.server.duration
   

   --metric-type 接受 Gauge、Sum、Histogram 或 ExponentialHistogram。

7. 在 ClickStack 中验证

   访问 http://localhost:8080 打开 ClickStack UI。在 搜索 视图中，将时间范围设置为 Last 15 minutes，并在 Logs 和 Traces 数据源之间切换。使用 ServiceName 过滤器查看 frontend、checkout、cart 和 payment 服务，再使用 SeverityText 过滤器查找警告和错误日志行。打开一条 payment trace，查看子 span 和错误状态。打开 Chart Explorer，选择 Metrics，然后将你在上面设置的某个指标名称 (例如 http.server.requests) 绘制成图表，以验证指标摄取。