使用 otelgen 生成模拟 OpenTelemetry 数据

otelgen 是一个轻量级的 Go CLI，可生成模拟 OTLP 日志、链路追踪和指标。你可以用它来确认现有的 ClickStack OpenTelemetry collector 是否正在接收数据，以及事件是否会显示在 ClickStack UI 中。本指南假设 collector 已在运行，并在 4317 (gRPC) 和 4318 (HTTP) 上提供 OTLP 端点。

托管 ClickStack
ClickStack 开源版

前置条件

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

安装 otelgen

使用 Homebrew 安装：

brew install krzko/tap/otelgen

或使用 Go 安装：

go install github.com/krzko/otelgen@latest

设置环境变量

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

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

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

未受保护的 collectorClickStack OpenTelemetry collector 默认不需要身份验证。如果你还没有按照保护 collector设置 OTLP_AUTH_TOKEN，这里可以跳过 OTLP_AUTH_TOKEN，并从下面的命令中去掉 --header 标志。

生成链路追踪

发送一小批包含多个 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 端口时，需要使用此选项。

生成日志

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

生成指标

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 子命令。

在 ClickStack 中验证

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

前置条件

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

安装 otelgen

使用 Homebrew 安装：

brew install krzko/tap/otelgen

或使用 Go 安装：

go install github.com/krzko/otelgen@latest

设置环境变量

导出 collector 端点和摄取 API key：

export OTEL_ENDPOINT=localhost:4317
export CLICKSTACK_API_KEY=<your_ingestion_api_key>

生成链路追踪

发送一小批包含多个 span 的链路追踪：

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。

生成日志

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

生成指标

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 子命令。

在 ClickStack 中验证

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