Monitoramento de traces do Nginx com o ClickStack

A forma mais fácil de adicionar rastreamento ao Nginx é usar a imagem oficial do Nginx com suporte nativo ao OpenTelemetry.

Usando a imagem nginx:otel

Substitua a imagem atual do Nginx pela versão com OpenTelemetry habilitado:

# No seu docker-compose.yml ou Dockerfile
image: nginx:1.27-otel

Essa imagem já inclui o ngx_otel_module.so, pronto para uso.

Adicione a configuração do OpenTelemetry ao arquivo nginx.conf. Essa configuração carrega o módulo e envia os traces para o endpoint OTLP do ClickStack.

Primeiro, obtenha sua API key:

1. Abra o HyperDX na URL do seu ClickStack
2. Vá para Settings → API Keys
3. Copie sua API key de ingestão
4. Defina-a como uma variável de ambiente: export CLICKSTACK_API_KEY=your-api-key-here

Adicione isto ao seu nginx.conf:

load_module modules/ngx_otel_module.so;

events {
    worker_connections 1024;
}

http {
    # Configuração do exporter do OpenTelemetry
    otel_exporter {
        endpoint <clickstack-host>:4317;
        header authorization ${CLICKSTACK_API_KEY};
    }
    
    # Nome do serviço para identificar esta instância do Nginx
    otel_service_name "nginx-proxy";
    
    # Habilita o rastreamento
    otel_trace on;
    
    server {
        listen 80;
        
        location / {
            # Habilita o rastreamento para este location
            otel_trace_context propagate;
            otel_span_name "$request_method $uri";
            
            # Adiciona detalhes da requisição aos traces
            otel_span_attr http.status_code $status;
            otel_span_attr http.request.method $request_method;
            otel_span_attr http.route $uri;
            
            # Sua configuração atual de proxy ou aplicação
            proxy_pass http://your-backend;
        }
    }
}

Se estiver executando o Nginx no Docker, passe a variável de ambiente para o contêiner:

services:
  nginx:
    image: nginx:1.27-otel
    environment:
      - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro

Substitua <clickstack-host> pelo hostname ou endereço IP da sua instância do ClickStack.

Entendendo a configuração

O que é rastreado: Cada requisição ao Nginx cria um trace span que mostra:

• Método e caminho da requisição
• Código de status HTTP
• Duração da requisição
• Timestamp

Atributos do span: As diretivas otel_span_attr adicionam metadados a cada trace, permitindo filtrar e analisar requisições no HyperDX por código de status, método, rota etc.

Depois de fazer essas alterações, teste a configuração do Nginx:

nginx -t

Se o teste passar, recarregue o Nginx:

# Para Docker
docker-compose restart nginx

# Para systemd
sudo systemctl reload nginx

Depois de configurar, faça login no HyperDX e verifique se os traces estão chegando. Você deverá ver algo como isto; se não vir traces, tente ajustar o intervalo de tempo:

Se o ClickStack ainda não estiver em execução, inicie-o com:

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

Aguarde cerca de 30 segundos até que o ClickStack inicialize completamente antes de prosseguir.

• Porta 8080: interface web do HyperDX
• Porta 4317: endpoint OTLP gRPC (usado pelo módulo do Nginx)
• Porta 4318: endpoint OTLP HTTP (usado para os traces de demonstração)

Baixe o arquivo de traces de exemplo e atualize os timestamps para o horário atual:

# Download dos traces
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nginx-traces-sample.json

O dataset inclui:

• 1.000 trace spans com tempos realistas
• 9 endpoints diferentes com padrões de tráfego variados
• ~93% de taxa de sucesso (200), ~3% de erros do cliente (404), ~4% de erros do servidor (500)
• Latências de 10ms a 800ms
• Padrões de tráfego originais preservados e deslocados para o horário atual

Defina sua API key como uma variável de ambiente (se ainda não estiver definida):

export CLICKSTACK_API_KEY=your-api-key-here

Obtenha sua API key:

1. Abra o HyperDX na URL do seu ClickStack
2. Vá para Settings → API Keys
3. Copie sua API key de ingestão

Em seguida, envie os traces para o ClickStack:

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nginx-traces-sample.json

Você deverá ver uma resposta como {"partialSuccess":{}}, indicando que os traces foram enviados com sucesso. Todos os 1.000 traces serão ingeridos pelo ClickStack.

1. Abra o HyperDX e faça login na sua conta (talvez seja necessário criar uma conta primeiro)
2. Vá para a visualização de Busca e defina a source como Traces
3. Defina o intervalo de tempo como 2025-10-25 13:00:00 - 2025-10-28 13:00:00

Veja o que deve aparecer na sua visualização de Busca:

Baixar o arquivo de configuração do dashboard.

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

3. Faça upload do arquivo nginx-trace-dashboard.json e clique em Finish Import.