Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Gere dados sintéticos do OpenTelemetry com telemetrygen

View as MarkdownEdit this pageReport an issueSet up docs MCP

telemetrygen é o gerador de dados do OpenTelemetry Collector Contrib. Ele emite logs, traces e métricas OTLP sintéticos e expõe flags que permitem definir o formato dos dados: vários serviços, severidades de log, status de span e spans filhos, além de diferentes tipos de métrica. Use-o para confirmar que um collector OpenTelemetry do ClickStack está aceitando dados e que eventos variados e realistas aparecem na ClickStack UI.

Este guia pressupõe que o collector já esteja em execução com endpoints OTLP nas portas 4317 (gRPC) e 4318 (HTTP).

Pré-requisitos

Este guia pressupõe que você tenha concluído o Guia de primeiros passos do Managed ClickStack e esteja com um coletor OpenTelemetry em execução, com os endpoints OTLP gRPC (4317) e HTTP (4318) acessíveis a partir da máquina em que você executa o telemetrygen. Se você protegeu o coletor com um OTLP_AUTH_TOKEN, mantenha esse valor em mãos.

Instalar o telemetrygen

Execute o telemetrygen a partir da sua imagem Docker (não é necessário instalar). Defina um pequeno wrapper para manter os comandos abaixo legíveis; --add-host permite que o contêiner acesse um collector em execução no host:

telemetrygen() {
  docker run --rm --add-host=host.docker.internal:host-gateway \
    ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:latest "$@"
}
export OTEL_ENDPOINT=host.docker.internal:4317

Ou instale o binário com Go e aponte para localhost:

go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
export OTEL_ENDPOINT=localhost:4317

Defina as variáveis de ambiente

Exporte o token de autenticação se o collector estiver protegido:

export OTLP_AUTH_TOKEN=<your_otlp_auth_token>

Defina um pequeno helper tg para que cada comando especifique apenas o que muda (serviço, severidade, status, atributos):

tg() { local signal=$1; shift; telemetrygen "$signal" \
  --otlp-endpoint ${OTEL_ENDPOINT} --otlp-insecure \
  --otlp-header "authorization=\"${OTLP_AUTH_TOKEN}\"" \
  --rate 5 --duration 30s "$@"; }

Gerar logs

Envie logs com uma combinação realista de níveis de severidade entre os serviços, em sua maioria informativos, com um aviso e um erro, em vez de um único fluxo uniforme:

tg logs --service frontend --severity-text Info  --severity-number 9  --body "GET /api/products 200" \
  --otlp-attributes 'deployment.environment="production"' \
  --telemetry-attributes 'http.method="GET"' --telemetry-attributes 'http.status_code="200"'
tg logs --service checkout --severity-text Warn  --severity-number 13 --body "retrying payment authorization" \
  --otlp-attributes 'deployment.environment="production"' \
  --telemetry-attributes 'http.method="POST"'
tg logs --service payment  --severity-text Error --severity-number 17 --body "payment gateway timeout" \
  --otlp-attributes 'deployment.environment="production"' \
  --telemetry-attributes 'http.status_code="500"'

As flags de log mais úteis:

  • --service define service.name para que os eventos possam ser atribuídos a um serviço.
  • --severity-text e --severity-number definem o nível (severity-number varia de 1 a 24).
  • --body define a mensagem de log.
  • --otlp-attributes define atributos em nível de recurso (key="value", key=true, ou key=<integer>).
  • --telemetry-attributes define atributos por registro.

Gerar traces

Envie traces com vários spans de diversos serviços saudáveis, além de uma dependência com falha. Isso dá ao Service Map uma configuração realista, majoritariamente saudável, com um serviço apresentando erros, e preenche as visualizações de erro:

# Healthy services: the bulk of the traffic, all spans Ok
for svc in frontend checkout cart; do
  tg traces --service "$svc" --child-spans 3 --span-duration 80ms --status-code Ok \
    --otlp-attributes 'deployment.environment="production"' \
    --telemetry-attributes "http.route=\"/$svc\""
done

# One slow dependency returning errors
tg traces --service payment --child-spans 3 --span-duration 450ms --span-links 1 --status-code Error \
  --otlp-attributes 'deployment.environment="production"' \
  --telemetry-attributes 'http.route="/charge"'

As flags de trace mais úteis:

  • --child-spans gera esse número de spans filhos em cada trace, dando profundidade real a cada trace.
  • --span-duration define quanto tempo cada span dura (por exemplo, 120ms, 2s).
  • --status-code pode ser Unset, Error, Ok (ou 0, 1, 2). Use Error para testar as visualizações de erro.
  • --span-links adiciona links entre spans.
  • --workers executa vários geradores em paralelo para gerar um volume maior e mais variado.

Gerar métricas

Envie os três tipos comuns de métricas para que os painéis tenham contadores, gauges e uma distribuição. Ao contrário de alguns geradores, o telemetrygen respeita --duration para métricas, então não é preciso interromper manualmente:

tg metrics --service frontend --metric-type Sum       --otlp-metric-name http.server.requests --aggregation-temporality cumulative
tg metrics --service frontend --metric-type Gauge     --otlp-metric-name system.memory.usage
tg metrics --service payment  --metric-type Histogram --otlp-metric-name http.server.duration

--metric-type aceita Gauge, Sum, Histogram ou ExponentialHistogram. --otlp-metric-name define o nome da série para que você possa encontrá-la na UI, e --aggregation-temporality é delta ou cumulative.

Verifique no ClickStack

Abra a UI do ClickStack no console do ClickHouse Cloud. Na visualização Busca, defina o intervalo de tempo como Last 15 minutes e alterne a origem entre Logs e Traces. Filtre por ServiceName para ver os serviços frontend, checkout, cart e payment, e por SeverityText para encontrar os logs de aviso e erro. Abra um trace de payment para ver os spans filhos e o status de erro. Abra o Chart Explorer, selecione Metrics e crie um gráfico para um dos nomes de métrica definidos acima (por exemplo, http.server.requests) para verificar a ingestão de métricas.

Navigation