Monitoramento dos logs do Nginx com ClickStack

Integração com o Nginx existente

Esta seção explica como configurar a sua instalação existente do Nginx para enviar logs ao ClickStack modificando a configuração do ClickStack OTel collector. Se quiser testar a integração antes de configurar o seu próprio ambiente, você pode usar nossa configuração pré-configurada e os dados de exemplo na seção a seguir.

Pré-requisitos

Instância do ClickStack em execução
Uma instalação existente do Nginx
Acesso para modificar arquivos de configuração do Nginx

Configure o formato dos logs do Nginx

Primeiro, configure o Nginx para gerar logs no formato JSON e facilitar o parsing. Adicione esta definição de formato de log ao seu nginx.conf:

O arquivo nginx.conf geralmente fica em:

Linux (apt/yum): /etc/nginx/nginx.conf
macOS (Homebrew): /usr/local/etc/nginx/nginx.conf ou /opt/homebrew/etc/nginx/nginx.conf
Docker: A configuração geralmente é montada como um volume

Adicione esta definição de formato de log ao bloco http:

http {
    log_format json_combined escape=json
    '{'
      '"time_local":"$time_local",'
      '"remote_addr":"$remote_addr",'
      '"request_method":"$request_method",'
      '"request_uri":"$request_uri",'
      '"status":$status,'
      '"body_bytes_sent":$body_bytes_sent,'
      '"request_time":$request_time,'
      '"upstream_response_time":"$upstream_response_time",'
      '"http_referer":"$http_referer",'
      '"http_user_agent":"$http_user_agent"'
    '}';

    access_log /var/log/nginx/access.log json_combined;
    error_log /var/log/nginx/error.log warn;
}

Após fazer essa alteração, recarregue o Nginx.

Crie uma configuração personalizada do OTel collector

O ClickStack permite estender a configuração básica do OpenTelemetry Collector montando um arquivo de configuração personalizado e definindo uma variável de ambiente. A configuração personalizada é mesclada à configuração básica gerenciada pelo HyperDX via OpAMP.

Crie um arquivo chamado nginx-monitoring.yaml com a seguinte configuração:

receivers:
  filelog:
    include:
      - /var/log/nginx/access.log
      - /var/log/nginx/error.log
    start_at: end 
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
      - type: time_parser
        parse_from: attributes.time_local
        layout: '%d/%b/%Y:%H:%M:%S %z'
      - type: add
        field: attributes.source
        value: "nginx"

service:
  pipelines:
    logs/nginx:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

Esta configuração:

Lê os logs do Nginx de seus locais padrão
Faz o parse de entradas de log em JSON
Extrai e preserva os timestamps originais dos logs
Adiciona o atributo source: Nginx para filtragem no HyperDX
Encaminha os logs para o ClickHouse exporter por meio de um pipeline dedicado

Configure o ClickStack para carregar uma configuração personalizada

Para habilitar uma configuração personalizada do collector na sua implantação existente do ClickStack, você deve:

Montar o arquivo de configuração personalizada em /etc/otelcol-contrib/custom.config.yaml
Definir a variável de ambiente CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Montar os diretórios de logs do Nginx para que o collector possa lê-los

Opção 1: Docker Compose

Atualize a configuração de implantação do ClickStack:

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/nginx:/var/log/nginx:ro
      # ... other volumes ...

Opção 2: Docker Run (Imagem all-in-one)

Se estiver usando a imagem all-in-one com docker run:

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log/nginx:/var/log/nginx:ro \
  clickhouse/clickstack-all-in-one:latest

Verificando logs no HyperDX

Depois de configurar, faça login no HyperDX e verifique se os logs estão sendo enviados:

Vá até a visualização Busca
Defina source como Logs e verifique se você vê entradas de log com campos como request, request_time, upstream_response_time etc.

Este é um exemplo do que você deve ver:

Conjunto de dados de exemplo

Para usuários que querem testar a integração do nginx antes de configurar seus sistemas de produção, fornecemos um dataset de exemplo com logs de acesso do nginx pré-gerados e padrões de tráfego realistas.

Baixe o dataset de exemplo

# Baixe os logs
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log

O dataset inclui:

Entradas de log com padrões de tráfego realistas
Vários endpoints e métodos HTTP
Uma combinação de solicitações bem-sucedidas e erros
Tempos de resposta e volumes de bytes realistas

Crie a configuração do collector de teste

Crie um arquivo chamado nginx-demo.yaml com a configuração a seguir:

cat > nginx-demo.yaml << 'EOF'
receivers:
  filelog:
    include:
      - /tmp/nginx-demo/access.log
    start_at: beginning  # Ler desde o início para os dados de exemplo
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
      - type: time_parser
        parse_from: attributes.time_local
        layout: '%d/%b/%Y:%H:%M:%S %z'
      - type: add
        field: attributes.source
        value: "nginx-demo"

service:
  pipelines:
    logs/nginx-demo:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

Execute o ClickStack com a configuração de demonstração

Execute o ClickStack com os logs e a configuração de demonstração:

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/nginx-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/access.log:/tmp/nginx-demo/access.log:ro" \
  clickhouse/clickstack-all-in-one:latest

Verifique os logs no HyperDX

Quando o ClickStack estiver em execução:

Abra o HyperDX e faça login na sua conta (talvez seja necessário criar uma conta primeiro)
Vá para a visualização Busca e defina a fonte como Logs
Defina o intervalo de tempo como 2025-10-19 11:00:00 - 2025-10-22 11:00:00

Veja o que você deverá ver na visualização Busca:

Dashboards e visualizações

Para ajudar você a começar a monitorar o Nginx com o ClickStack, fornecemos visualizações essenciais para os logs do Nginx.

Baixar a configuração do dashboard

Baixar o arquivo de configuração do dashboard.

Importe o dashboard pré-configurado

Abra o HyperDX e vá para a seção Dashboards.
Clique em "Import Dashboard" no canto superior direito, no menu de reticências.

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

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

Solução de problemas

Config personalizada não é carregada

Verifique se a variável de ambiente CUSTOM_OTELCOL_CONFIG_FILE está definida corretamente

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Verifique se o arquivo de configuração personalizado está montado em /etc/otelcol-contrib/custom.config.yaml

docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml

Verifique o conteúdo da configuração personalizada para confirmar se está legível

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml

Os logs não estão aparecendo no HyperDX

Certifique-se de que o nginx esteja gravando logs em JSON

tail -f /var/log/nginx/access.log

Verifique se o collector consegue ler os logs

docker exec `<container>` cat /var/log/nginx/access.log

Verifique se a config efetiva inclui o receiver filelog

docker exec `<container>` cat /etc/otel/supervisor-data/effective.yaml | grep filelog

Verifique se há erros nos logs do collector

docker exec `<container>` cat /etc/otel/supervisor-data/agent.log

Próximos passos

Configure alertas para métricas críticas (taxas de erro, limites de latência)
Crie dashboards adicionais para casos de uso específicos (monitoramento de APIs, eventos de segurança)

Em produção

Este guia aproveita o OpenTelemetry Collector integrado do ClickStack para uma configuração rápida. Para implantações em produção, recomendamos executar seu próprio OTel Collector e enviar os dados para o endpoint OTLP do ClickStack. Consulte Enviando dados do OpenTelemetry para a configuração de produção.