> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 otelgen 生成模拟 OpenTelemetry 数据

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

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

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

<Tabs>
  <Tab title="托管 ClickStack">
    <Steps>
      <Step title="前置条件" id="prerequisites-managed">
        本指南假设你已经完成[托管 ClickStack 入门指南](/docs/zh/clickstack/deployment/managed)，并且已有一个正在运行的 OpenTelemetry Collector，其 OTLP gRPC (`4317`) 和 HTTP (`4318`) 端点可从运行 `otelgen` 的机器访问。如果你已按照[保护 collector](/docs/zh/clickstack/ingesting-data/collector#securing-the-collector)使用 `OTLP_AUTH_TOKEN` 保护了 collector，请提前准备好该值。
      </Step>

      <Step title="安装 otelgen" id="install-otelgen-managed">
        使用 Homebrew 安装：

        ```shell theme={null}
        brew install krzko/tap/otelgen
        ```

        或使用 Go 安装：

        ```shell theme={null}
        go install github.com/krzko/otelgen@latest
        ```
      </Step>

      <Step title="设置环境变量" id="set-env-vars-managed">
        导出 collector 端点；如果 collector 已启用保护，再导出认证令牌：

        ```shell theme={null}
        export OTEL_ENDPOINT=<host>:4317
        export OTLP_AUTH_TOKEN=<your_otlp_auth_token>
        ```

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

        <Info>
          **未受保护的 collector**

          ClickStack OpenTelemetry collector 默认不需要身份验证。如果你还没有按照[保护 collector](/docs/zh/clickstack/ingesting-data/collector#securing-the-collector)设置 `OTLP_AUTH_TOKEN`，这里可以跳过 `OTLP_AUTH_TOKEN`，并从下面的命令中去掉 `--header` 标志。
        </Info>
      </Step>

      <Step title="生成链路追踪" id="generate-traces-managed">
        发送一小批包含多个 span 的链路追踪数据：

        ```shell theme={null}
        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 端口时，需要使用此选项。
      </Step>

      <Step title="生成日志" id="generate-logs-managed">
        ```shell theme={null}
        otelgen --otel-exporter-otlp-endpoint ${OTEL_ENDPOINT} \
          --header "authorization=${OTLP_AUTH_TOKEN}" \
          --protocol grpc --insecure \
          --rate 2 --duration 10 \
          logs multi
        ```
      </Step>

      <Step title="生成指标" id="generate-metrics-managed">
        `metrics` 子命令不支持 `--duration`。运行该命令后，等待几秒钟再按 `Ctrl+C` 停止。

        ```shell theme={null}
        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` 子命令。
      </Step>

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

  <Tab title="ClickStack 开源版">
    <Steps>
      <Step title="前置条件" id="prerequisites-oss">
        本指南假定你已按照[一体化镜像说明](/docs/zh/clickstack/getting-started/oss)启动开源 ClickStack，并且 OTLP 端点 (`4317` gRPC 和 `4318` HTTP) 可访问。你还需要从 HyperDX UI 的 `Team Settings > API Keys` 获取摄取 API key。
      </Step>

      <Step title="安装 otelgen" id="install-otelgen-oss">
        使用 Homebrew 安装：

        ```shell theme={null}
        brew install krzko/tap/otelgen
        ```

        或使用 Go 安装：

        ```shell theme={null}
        go install github.com/krzko/otelgen@latest
        ```
      </Step>

      <Step title="设置环境变量" id="set-env-vars-oss">
        导出 collector 端点和摄取 API key：

        ```shell theme={null}
        export OTEL_ENDPOINT=localhost:4317
        export CLICKSTACK_API_KEY=<your_ingestion_api_key>
        ```
      </Step>

      <Step title="生成链路追踪" id="generate-traces-oss">
        发送一小批包含多个 span 的链路追踪：

        ```shell theme={null}
        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。
      </Step>

      <Step title="生成日志" id="generate-logs-oss">
        ```shell theme={null}
        otelgen --otel-exporter-otlp-endpoint ${OTEL_ENDPOINT} \
          --header "authorization=${CLICKSTACK_API_KEY}" \
          --protocol grpc --insecure \
          --rate 2 --duration 10 \
          logs multi
        ```
      </Step>

      <Step title="生成指标" id="generate-metrics-oss">
        `metrics` 子命令不支持 `--duration`。运行该命令后，等待几秒钟，再按 `Ctrl+C` 停止。

        ```shell theme={null}
        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` 子命令。
      </Step>

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