使用 otelgen 生成模拟 OpenTelemetry 数据

使用 otelgen 将模拟日志、链路追踪和指标发送到 ClickStack OpenTelemetry collector

otelgen 是一个轻量级的 Go CLI，可生成模拟 OTLP 日志、链路追踪和指标。你可以用它来确认现有的 ClickStack OpenTelemetry collector 是否正在接收数据，以及事件是否会显示在 ClickStack UI 中。

本指南假设 collector 已在运行，并在 4317 (gRPC) 和 4318 (HTTP) 上提供 OTLP 端点。

托管 ClickStack

1. ​

   前置条件

   本指南假设你已完成托管 ClickStack 入门指南，并且已有一个正在运行的 OpenTelemetry collector，且你运行 otelgen 的机器可以访问其 OTLP gRPC (4317) 和 HTTP (4318) 端点。如果你已使用 OTLP_AUTH_TOKEN 保护 collector，请提前准备好该值。

2. ​

   安装 otelgen

   使用 Homebrew 安装：

   brew install krzko/tap/otelgen
   

   或使用 Go 安装：

   go install github.com/krzko/otelgen@latest
   
3. ​

   设置环境变量

   导出 collector 端点；如果 collector 已启用保护，还需要导出认证令牌：

   export OTEL_ENDPOINT=<host>:4317
   export OTLP_AUTH_TOKEN=<your_otlp_auth_token>
   

   请使用你的 collector 的主机名和端口。如果 collector 运行在同一台机器上，则应为 localhost:4317。

   未受保护的 collector

   ClickStack OpenTelemetry collector 默认不启用身份验证。如果你尚未按照保护 collector设置 OTLP_AUTH_TOKEN，此处可跳过 OTLP_AUTH_TOKEN，并从下面的命令中移除 --header 标志。

4. ​

   生成链路追踪

   发送一小段包含多个 span 的链路追踪数据：

   otelgen --otel-exporter-otlp-endpoint ${OTEL_ENDPOINT} \
     --header "authorization=${OTLP_AUTH_TOKEN}" \
     --protocol grpc --insecure \
     --rate 2 --duration 10 \
     traces multi
   

   --rate 表示每秒生成的 trace 数，--duration 表示运行时长 (秒) 。--insecure 会禁用 gRPC 连接上的 TLS；当 otelgen 指向 collector 的明文 OTLP 端口时，需要使用该选项。

5. ​

   生成日志

   otelgen --otel-exporter-otlp-endpoint ${OTEL_ENDPOINT} \
     --header "authorization=${OTLP_AUTH_TOKEN}" \
     --protocol grpc --insecure \
     --rate 2 --duration 10 \
     logs multi
   
6. ​

   生成指标

   metrics 子命令不支持 --duration。运行该命令后，等待几秒钟，再按 Ctrl+C 停止。

   otelgen --otel-exporter-otlp-endpoint ${OTEL_ENDPOINT} \
     --header "authorization=${OTLP_AUTH_TOKEN}" \
     --protocol grpc --insecure \
     --rate 2 \
     metrics sum
   

   otelgen 还支持 metrics 下的 gauge、histogram、up-down-counter 和 exponential-histogram 子命令。

7. ​

   在 ClickStack 中验证

   从 ClickHouse Cloud 控制台打开 ClickStack UI。在 Search 视图中，在 Logs 和 Traces 之间切换 source，确认是否有新事件。将时间范围设置为 Last 15 minutes。打开 Chart Explorer，选择 Metrics，然后将 otelgen 生成的某个指标名称绘制为图表 (例如 otelgen.metrics.sum) ，以验证指标摄取是否成功。

ClickStack 开源版

1. ​

   前置条件

   本指南假设你已按照all-in-one image 的说明启动开源 ClickStack，并且 OTLP 端点 (4317 gRPC 和 4318 HTTP) 可访问。你还需要从 HyperDX UI 的 Team Settings > API Keys 中获取摄取 API key。

2. ​

   安装 otelgen

   使用 Homebrew 安装：

   brew install krzko/tap/otelgen
   

   或使用 Go 安装：

   go install github.com/krzko/otelgen@latest
   
3. ​

   设置环境变量

   导出 collector 端点和摄取 API key：

   export OTEL_ENDPOINT=localhost:4317
   export CLICKSTACK_API_KEY=<your_ingestion_api_key>
   
4. ​

   生成链路追踪

   发送一小批包含多个 span 的 trace：

   otelgen --otel-exporter-otlp-endpoint ${OTEL_ENDPOINT} \
     --header "authorization=${CLICKSTACK_API_KEY}" \
     --protocol grpc --insecure \
     --rate 2 --duration 10 \
     traces multi
   

   --rate 表示每秒生成的 trace 数，--duration 表示运行时长 (单位为秒) 。--insecure 会针对本地 collector 启用明文 gRPC。

5. ​

   生成日志

   otelgen --otel-exporter-otlp-endpoint ${OTEL_ENDPOINT} \
     --header "authorization=${CLICKSTACK_API_KEY}" \
     --protocol grpc --insecure \
     --rate 2 --duration 10 \
     logs multi
   
6. ​

   生成指标

   metrics 子命令不支持 --duration。运行命令后，几秒钟后按 Ctrl+C 停止。

   otelgen --otel-exporter-otlp-endpoint ${OTEL_ENDPOINT} \
     --header "authorization=${CLICKSTACK_API_KEY}" \
     --protocol grpc --insecure \
     --rate 2 \
     metrics sum
   

   otelgen 还支持 metrics 下的 gauge、histogram、up-down-counter 和 exponential-histogram 子命令。

7. ​

   在 ClickStack 中验证

   访问 http://localhost:8080 打开 ClickStack UI。在 搜索 视图中，在 Logs 和 Traces 之间切换数据源，以确认有新事件写入。将时间范围设置为 Last 15 minutes。打开 Chart Explorer，选择 Metrics，然后将 otelgen 生成的某个指标名称绘制为图表 (例如 otelgen.metrics.sum) ，以验证指标摄取是否成功。