Monitoramento dos logs do Nginx com ClickStack

TL;DRColete e visualize os logs de acesso do Nginx (formato JSON) no ClickStack usando o receiver filelog do OTel. Inclui um conjunto de dados de demonstração e um dashboard pré-configurado.

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

Você define apenas novos receivers e pipelines na configuração personalizada
Os processors (memory_limiter, transform, batch) e exporters (clickhouse) já estão definidos na configuração base do ClickStack — você só faz referência a eles pelo nome
O operador time_parser extrai timestamps do campo time_local do Nginx para preservar o horário original dos logs
Os pipelines encaminham dados dos seus receivers para o ClickHouse exporter por meio dos processors existentes

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:
    # ... configuração existente ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... outras variáveis de ambiente ...
    volumes:
      - ./nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/nginx:/var/log/nginx:ro
      # ... outros 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

Garanta que o ClickStack collector tenha as permissões adequadas para ler os arquivos de log do nginx. Em produção, use montagens em modo somente leitura (:ro) e siga o princípio do privilégio mínimo.

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 demonstração

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 demonstração
    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:

Exibição de fuso horárioO HyperDX exibe os timestamps no fuso horário local do seu navegador. Os dados de demonstração cobrem 2025-10-20 11:00:00 - 2025-10-21 11:00:00 UTC. O intervalo de tempo amplo garante que você verá os logs de demonstração independentemente da sua localização. Depois de visualizar os logs, você pode reduzir o intervalo para um período de 24 horas para ter visualizações mais claras.

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.

a 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

Para o conjunto de dados de demonstração, defina o intervalo de tempo como 2025-10-20 11:00:00 - 2025-10-21 11:00:00 (UTC) (ajuste com base no seu fuso horário local). Por padrão, o dashboard importado não terá um intervalo de tempo especificado.

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)

Colocando 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.

​Integração com o Nginx existente

Pré-requisitos

​Configure o formato dos logs do Nginx

​Crie uma configuração personalizada do OTel collector

​Configure o ClickStack para carregar uma configuração personalizada

Opção 1: Docker Compose

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

​Verificando logs no HyperDX

​Conjunto de dados de demonstração

​Baixe o dataset de exemplo

​Crie a configuração do collector de teste

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

​Verifique os logs no HyperDX

​Dashboards e visualizações

​ a configuração do dashboard

​Importe o dashboard pré-configurado

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

​Solução de problemas

​Config personalizada não é carregada

​Os logs não estão aparecendo no HyperDX

​Próximos passos

​Colocando em produção

Integração com o Nginx existente

Configure o formato dos logs do Nginx

Crie uma configuração personalizada do OTel collector

Configure o ClickStack para carregar uma configuração personalizada

Verificando logs no HyperDX

Conjunto de dados de demonstração

Baixe o dataset de exemplo

Crie a configuração do collector de teste

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

Verifique os logs no HyperDX

Dashboards e visualizações

a configuração do dashboard

Importe o dashboard pré-configurado

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

Solução de problemas

Config personalizada não é carregada

Os logs não estão aparecendo no HyperDX

Próximos passos

Colocando em produção