Monitoramento de métricas da JVM com ClickStack

Integração com uma aplicação JVM existente

Esta seção aborda como configurar sua aplicação JVM existente para enviar métricas para o ClickStack usando o agente Java do OpenTelemetry.

Se quiser testar a integração antes de configurar seu ambiente de produção, você pode usar nosso conjunto de dados de demonstração na seção sobre o conjunto de dados de demonstração.

Pré-requisitos

Instância do ClickStack em execução
Aplicação Java existente (Java 8+)
Acesso para modificar os argumentos de inicialização da JVM

Obtenha a API key do ClickStack

O agente Java do OpenTelemetry envia dados para o endpoint OTLP do ClickStack, que requer autenticação.

Abra o HyperDX na URL do seu ClickStack (por exemplo, http://localhost:8080)
Crie uma conta ou faça login, se necessário
Acesse Team Settings → API Keys
Copie sua API key de ingestão

Baixe o agente Java do OpenTelemetry

Baixe o arquivo JAR do agente Java do OpenTelemetry:

curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.22.0/opentelemetry-javaagent.jar

Isso baixa o agente para o diretório atual. Você pode colocá-lo onde fizer mais sentido para sua implantação (por exemplo, /opt/opentelemetry/ ou ao lado do JAR da sua aplicação).

Configure os argumentos de inicialização da JVM

Adicione o Java agent ao comando de inicialização da JVM. O agente coleta automaticamente métricas da JVM e as envia ao ClickStack.

Opção 1: Flags de linha de comando

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.service.name=my-java-app \
  -Dotel.exporter.otlp.endpoint=http://localhost:4318 \
  -Dotel.exporter.otlp.protocol=http/protobuf \
  -Dotel.exporter.otlp.headers="authorization=YOUR_API_KEY" \
  -Dotel.metrics.exporter=otlp \
  -Dotel.logs.exporter=none \
  -Dotel.traces.exporter=none \
  -jar my-application.jar

Substitua o seguinte:

opentelemetry-javaagent.jar → Caminho completo para o JAR do agente (por exemplo, /opt/opentelemetry/opentelemetry-javaagent.jar)
my-java-app → Um nome descritivo para o seu serviço (por exemplo, payment-service, user-api)
YOUR_API_KEY → Sua API key do ClickStack obtida na etapa anterior
my-application.jar → Nome do arquivo JAR da sua aplicação
http://localhost:4318 → Endpoint do seu ClickStack (use localhost:4318 se o ClickStack estiver em execução na mesma máquina; caso contrário, use http://your-clickstack-host:4318)

Opção 2: Variáveis de ambiente

Como alternativa, use variáveis de ambiente:

export JAVA_TOOL_OPTIONS="-javaagent:opentelemetry-javaagent.jar"
export OTEL_SERVICE_NAME="my-java-app"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="authorization=YOUR_API_KEY"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="none"
export OTEL_TRACES_EXPORTER="none"

java -jar my-application.jar

Substitua o seguinte:

opentelemetry-javaagent.jar → Caminho completo para o JAR do agente
my-java-app → Nome do seu serviço
YOUR_API_KEY → Sua API key do ClickStack
http://localhost:4318 → Endpoint do seu ClickStack
my-application.jar → Nome do arquivo JAR da sua aplicação

Verifique as métricas no HyperDX

Depois que sua aplicação estiver em execução com o agente, verifique se as métricas estão chegando ao ClickStack:

Abra o HyperDX em http://localhost:8080 (ou na URL do seu ClickStack)
Acesse Chart Explorer
Procure métricas que comecem com jvm. (por exemplo, jvm.memory.used, jvm.gc.duration, jvm.thread.count)

Conjunto de dados de demonstração

Para usuários que querem testar a integração de métricas da JVM antes de instrumentar suas aplicações, fornecemos um conjunto de dados de exemplo com métricas pré-geradas que mostram um comportamento realista da JVM em um microsserviço de médio porte com tráfego moderado e constante.

Baixe o conjunto de dados de exemplo

# Baixe métricas gauge (memória, threads, CPU, classes)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/jvm/jvm-metrics-gauge.jsonl

# Baixe métricas sum (eventos de GC)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/jvm/jvm-metrics-sum.jsonl

O conjunto de dados inclui 24 horas de métricas da JVM, mostrando:

Crescimento da memória heap com eventos periódicos de coleta de lixo
Variações na contagem de threads
Tempos de pausa de GC realistas
Atividade de carregamento de classes
Padrões de uso de CPU

Inicie o ClickStack

Se o ClickStack ainda não estiver em execução:

docker run -d --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest

Aguarde alguns instantes até que o ClickStack seja iniciado completamente.

Importe o conjunto de dados de demonstração

# Importe métricas gauge (memória, threads, CPU, classes)
docker exec -i clickstack clickhouse-client --query="
  INSERT INTO default.otel_metrics_gauge FORMAT JSONEachRow
" < jvm-metrics-gauge.jsonl

# Importe métricas sum (eventos de GC)
docker exec -i clickstack clickhouse-client --query="
  INSERT INTO default.otel_metrics_sum FORMAT JSONEachRow
" < jvm-metrics-sum.jsonl

Isso importa as métricas diretamente para as tabelas de métricas do ClickStack.

Verifique os dados de demonstração

Depois da importação:

Abra o HyperDX em http://localhost:8080 e faça login (crie uma conta, se necessário)
Vá para a Search view e defina a source como Metrics
Defina o intervalo de tempo como 2025-12-06 14:00:00 - 2025-12-09 14:00:00
Pesquise por jvm.memory.used ou jvm.gc.duration

Você deverá ver métricas do serviço de demonstração.

Dashboards e visualização

Para ajudar você a monitorar aplicações JVM com o ClickStack, fornecemos um dashboard pré-configurado com visualizações essenciais para métricas de JVM.

Baixar a configuração do dashboard

Baixar o arquivo de configuração do dashboard.

Importe o dashboard pré-configurado

Abra o HyperDX e navegue até a seção Dashboards
Clique em Import Dashboard no canto superior direito, no menu de reticências

Faça upload do arquivo jvm-metrics-dashboard.json e clique em Finish Import

Visualize o dashboard

O dashboard será criado com todas as visualizações pré-configuradas:

Solução de problemas

Agente não inicia

Verifique se o JAR do agente existe:

ls -lh /path/to/opentelemetry-javaagent.jar

Verifique a compatibilidade com a versão do Java (requer Java 8+):

java -version

Procure pela mensagem de log de inicialização do agente: Quando sua aplicação iniciar, você deverá ver:

[otel.javaagent] OpenTelemetry Javaagent v2.22.0 started

Nenhuma métrica aparece no HyperDX

Verifique se o ClickStack está em execução e acessível:

docker ps | grep clickstack
curl -v http://localhost:4318/v1/metrics

Verifique se o exporter de métricas está configurado:

# Se estiver usando variáveis de ambiente, verifique:
echo $OTEL_METRICS_EXPORTER
# Saída esperada: otlp

Verifique os logs da aplicação em busca de erros do OpenTelemetry: Procure mensagens de erro relacionadas ao OpenTelemetry ou a falhas na exportação via OTLP nos logs da sua aplicação.

Verifique a conectividade de rede: Se o ClickStack estiver em um host remoto, verifique se a porta 4318 está acessível a partir do servidor da sua aplicação.

Verifique a versão do agente: Verifique se você está usando a versão estável mais recente do agente (atualmente, 2.22.0), pois versões mais novas costumam incluir melhorias de desempenho.

Próximos passos

Configure alertas para métricas críticas, como alto uso de heap, pausas frequentes de GC ou esgotamento de threads
Explore outras integrações do ClickStack para unificar seus dados de observabilidade

Indo para produção

Este guia demonstra como configurar o agente Java do OpenTelemetry para testes locais. Para implantações em produção, inclua o JAR do agente nas imagens de contêiner e configure-o por meio de variáveis de ambiente para facilitar o gerenciamento. Para ambientes maiores com muitas instâncias de JVM, implante um OpenTelemetry Collector centralizado para agrupar em lotes e encaminhar métricas de várias aplicações, em vez de enviá-las diretamente ao ClickStack.

Consulte Ingestão com OpenTelemetry para ver padrões de implantação em produção e exemplos de configuração do coletor.