Generate synthetic OpenTelemetry data with otelgen

otelgen is a small Go CLI that generates synthetic OTLP logs, traces and metrics. Use it to confirm that an existing ClickStack OpenTelemetry collector is accepting data and that events surface in the ClickStack UI.

This guide assumes the collector is already running with OTLP endpoints on 4317 (gRPC) and 4318 (HTTP).

Managed ClickStack

Prerequisites

This guide assumes you have completed the Getting Started Guide for Managed ClickStack and have an OpenTelemetry collector running with the OTLP gRPC (4317) and HTTP (4318) endpoints reachable from the machine you run otelgen on. If you secured the collector with an OTLP_AUTH_TOKEN, keep that value handy.

Install otelgen

Install with Homebrew:

brew install krzko/tap/otelgen

Or install with Go:

go install github.com/krzko/otelgen@latest

Set environment variables

Export the collector endpoint and, if the collector is secured, the auth token:

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

Use the host and port of your collector. For a collector running on the same machine, this is localhost:4317.

Unsecured collector

The ClickStack OpenTelemetry collector is unauthenticated by default. If you haven't followed Securing the collector to set an OTLP_AUTH_TOKEN, skip OTLP_AUTH_TOKEN here and drop the --header flag from the commands below.

Generate traces

Send a short burst of multi-span traces:

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

--rate is traces per second and --duration is the run length in seconds. --insecure disables TLS on the gRPC connection, which is needed when pointing otelgen at the collector's plaintext OTLP port.

Generate logs

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

Generate metrics

The metrics subcommands don't honor --duration. Run the command and press Ctrl+C after a few seconds to stop it.

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

otelgen also supports gauge, histogram, up-down-counter and exponential-histogram subcommands under metrics.

Verify in ClickStack

Open the ClickStack UI from the ClickHouse Cloud console. In the Search view, switch the source between Logs and Traces to confirm new events. Set the time range to Last 15 minutes. Open the Chart Explorer, select Metrics, and chart one of the metric names produced by otelgen (for example otelgen.metrics.sum) to verify metrics ingestion.

ClickStack Open Source

Prerequisites

This guide assumes you have started Open Source ClickStack using the instructions for the all-in-one image, and that the OTLP endpoints (4317 gRPC and 4318 HTTP) are reachable. You also need the ingestion API key from the HyperDX UI under Team Settings > API Keys.

Install otelgen

Install with Homebrew:

brew install krzko/tap/otelgen

Or install with Go:

go install github.com/krzko/otelgen@latest

Set environment variables

Export the collector endpoint and the ingestion API key:

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

Generate traces

Send a short burst of multi-span traces:

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

--rate is traces per second and --duration is the run length in seconds. --insecure enables plaintext gRPC against the local collector.

Generate logs

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

Generate metrics

The metrics subcommands don't honor --duration. Run the command and press Ctrl+C after a few seconds to stop it.

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

otelgen also supports gauge, histogram, up-down-counter and exponential-histogram subcommands under metrics.

Verify in ClickStack

Visit http://localhost:8080 to open the ClickStack UI. In the Search view, switch the source between Logs and Traces to confirm new events. Set the time range to Last 15 minutes. Open the Chart Explorer, select Metrics, and chart one of the metric names produced by otelgen (for example otelgen.metrics.sum) to verify metrics ingestion.