Gerar dados sintéticos do OpenTelemetry com otelgen

otelgen é uma pequena CLI escrita em Go que gera logs, traces e métricas sintéticos via OTLP. Use-o para confirmar que um coletor OpenTelemetry do ClickStack já está aceitando dados e que os eventos aparecem na UI do ClickStack. Este guia pressupõe que o coletor já esteja em execução com endpoints OTLP nas portas 4317 (gRPC) e 4318 (HTTP).

ClickStack Gerenciado
ClickStack Open Source

Pré-requisitos

Este guia pressupõe que você concluiu o guia de primeiros passos do Managed ClickStack e tem um collector do OpenTelemetry em execução, com os endpoints OTLP gRPC (4317) e HTTP (4318) acessíveis a partir da máquina em que o otelgen é executado. Se você protegeu o collector com um OTLP_AUTH_TOKEN, deixe esse valor à mão.

Instalar o otelgen

Instale com Homebrew:

brew install krzko/tap/otelgen

Ou instale com Go:

go install github.com/krzko/otelgen@latest

Definir variáveis de ambiente

Exporte o endpoint do collector e, se ele estiver protegido, o token de autenticação:

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

Use o host e a porta do seu collector. Se ele estiver em execução na mesma máquina, use localhost:4317.

Collector sem autenticaçãoO ClickStack OpenTelemetry collector não exige autenticação por padrão. Se você não seguiu Securing the collector para definir um OTLP_AUTH_TOKEN, ignore OTLP_AUTH_TOKEN aqui e remova a flag --header dos comandos abaixo.

Gerar traces

Envie uma breve rajada de traces com vários spans:

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

--rate indica o número de traces por segundo, e --duration é a duração da execução em segundos. --insecure desativa o TLS na conexão gRPC, o que é necessário ao apontar o otelgen para a porta OTLP sem criptografia do collector.

Gerar logs

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

Gerar métricas

Os subcomandos de métricas não respeitam --duration. Execute o comando e pressione Ctrl+C após alguns segundos para interrompê-lo.

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

O otelgen também oferece suporte aos subcomandos gauge, histogram, up-down-counter e exponential-histogram em metrics.

Verificar no ClickStack

Abra a UI do ClickStack pelo console do ClickHouse Cloud. Na visualização Busca, alterne a source entre Logs e Traces para confirmar os novos eventos. Defina o intervalo de tempo como Last 15 minutes. Abra o Chart Explorer, selecione Metrics e crie um gráfico com um dos nomes de métricas produzidos pelo otelgen (por exemplo, otelgen.metrics.sum) para verificar a ingestão de métricas.

Pré-requisitos

Este guia pressupõe que você iniciou o Open Source ClickStack usando as instruções da imagem all-in-one e que os endpoints OTLP (4317 gRPC e 4318 HTTP) estejam acessíveis. Você também precisará da API key de ingestão na interface do HyperDX, em Team Settings > API Keys.

Instalar o otelgen

Instale com Homebrew:

brew install krzko/tap/otelgen

Ou instale com Go:

go install github.com/krzko/otelgen@latest

Definir variáveis de ambiente

Exporte o endpoint do collector e a API key de ingestão:

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

Gerar traces

Envie uma pequena sequência de traces com vários spans:

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

--rate é o número de traces por segundo, e --duration é a duração da execução em segundos. --insecure habilita gRPC em plaintext no collector local.

Gerar logs

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

Gerar métricas

Os subcomandos de métricas não respeitam --duration. Execute o comando e pressione Ctrl+C após alguns segundos para interrompê-lo.

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

O otelgen também oferece suporte aos subcomandos gauge, histogram, up-down-counter e exponential-histogram em metrics.

Verificar no ClickStack

Acesse http://localhost:8080 para abrir a UI do ClickStack. Na visualização Busca, alterne a source entre Logs e Traces para confirmar os novos eventos. Defina o intervalo de tempo como Last 15 minutes. Abra o Chart Explorer, selecione Metrics e crie um gráfico com um dos nomes de métrica gerados pelo otelgen (por exemplo, otelgen.metrics.sum) para verificar a ingestão de métricas.

Funcionalidades

Guias

Gerar dados sintéticos do OpenTelemetry com otelgen