Monitoramento Nginx com Grafana e Prometheus

Introdução à Observabilidade de Logs Nginx com Grafana

No cenário atual de infraestrutura, saber o que acontece dentro do seu servidor web é tão crítico quanto monitorar a CPU ou a memória. O Nginx é um dos servidores web mais utilizados no mundo, e seus logs de acesso contêm dados valiosíssimos sobre tráfego, erros, latência e comportamento dos usuários. No entanto, analisar esses logs manualmente em arquivos de texto planos não escala bem em ambientes modernos.

A solução ideal para transformar dados brutos em inteligência visual é criar Dashboards Grafana que agreguem informações de fontes diversas. Neste tutorial, vamos construir um pipeline de observabilidade robusto onde os logs de acesso do Nginx são parseados e expostos via Prometheus, permitindo visualizações dinâmicas e alertas em tempo real.

Embora ferramentas como Zabbix, Uptime Kuma e LibreNMS sejam excelentes para monitoramento de infraestrutura tradicional (up/down, latência de ping, uso de recursos), elas muitas vezes carecem da profundidade analítica necessária para métricas de aplicação HTTP. Ao integrar o Grafana com Prometheus para logs de acesso, você ganha a capacidade de responder perguntas como: "Qual endpoint está retornando mais erros 500?", "Qual é o tráfego por país?" ou "Houve um pico de requisições não autorizadas (401) nos últimos 15 minutos?".

Arquitetura da Solução

Antes de configurar qualquer software, é fundamental entender como os componentes se comunicam. Para monitorar logs de acesso do Nginx no Grafana, utilizaremos a seguinte arquitetura:

• Nginx: Gera os logs no formato padrão ou personalizado.
• nginx-exporter (ou prometheus-nginxlog-exporter): Um sidecar ou serviço que lê os logs do Nginx em tempo real, faz o parse dos campos e os expõe como métricas Prometheus (histogramas e contadores).
• Prometheus: Coleta essas métricas periodicamente e as armazena no seu banco de dados de séries temporais.
• Grafana: Conecta-se ao Prometheus, consulta as métricas e renderiza os painéis visuais.

Diferente do Zabbix ou LibreNMS, que geralmente monitoram o estado do serviço, esta abordagem monitora o conteúdo das requisições HTTP. Isso permite a criação de alertas granulares no Grafana, como notificações via Telegram quando a taxa de erros ultrapassa um limiar.

Passo 1: Preparação do Ambiente e Instalação do Nginx

Vamos assumir que você está em um ambiente Linux Debian/Ubuntu (comandos adaptáveis para RHEL/CentOS). Primeiro, garanta que o Nginx está instalado e rodando.

1. Instale o Nginx:

sudo apt update
sudo apt install nginx -y

Verifique se o serviço está ativo:

sudo systemctl status nginx

O formato de log padrão do Nginx geralmente não contém todos os campos que queremos (como tempo de resposta em milissegundos ou tamanho exato da resposta de forma clara). Vamos personalizar o formato para capturar dados essenciais. Edite o arquivo de configuração do site:

sudo nano /etc/nginx/sites-available/default

No bloco http (ou no server block, dependendo da sua estrutura), defina um novo log_format. Um formato recomendado para métricas é:

log_format access_metrics '$remote_addr - $remote_user [$time_local] '
                          '"$request" $status $body_bytes_sent '
                          '"$http_referer" "$http_user_agent" '
                          '$request_time $upstream_response_time';

Em seguida, aplique este formato ao seu log de acesso:

access_log /var/log/nginx/access.log access_metrics;

Recarregue o Nginx para aplicar as mudanças:

sudo systemctl reload nginx

Passo 2: Instalando e Configurando o Exportador de Logs

O Prometheus não sabe ler logs diretamente. Precisamos de um exportador que converta linhas de log em métricas. O prometheus-nginxlog-exporter é uma escolha leve e eficiente.

1. Baixe o binário mais recente do GitHub (ajuste a versão conforme necessário):

sudo wget https://github.com/nginxinc/prometheus-nginxlog-exporter/releases/download/v3.0.0/prometheus_nginxlog_exporter_3.0.0_linux_amd64.tar.gz
sudo tar -xzf prometheus_nginxlog_exporter_3.0.0_linux_amd64.tar.gz

Crie um usuário dedicado para segurança:

sudo useradd --no-create-home --shell /bin/false nginx-exporter

Mova o binário e ajuste permissões:

sudo mv prometheus_nginxlog_exporter /usr/local/bin/
sudo chown root:root /usr/local/bin/prometheus_nginxlog_exporter
sudo chmod 755 /usr/local/bin/prometheus_nginxlog_exporter

Agora, crie um arquivo de configuração YAML para o exportador. Este arquivo define como as linhas de log devem ser interpretadas:

sudo nano /etc/prometheus-nginxlog-exporter.yaml

Insira a seguinte configuração, alinhando-a com o log_format definido no Nginx:

listen: 0.0.0.0
port: 4040
scrape_interval: 15s
metrics_path: /metrics
log_files:
- /var/log/nginx/access.log
log_format: '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_time $upstream_response_time'
metric_namespaces:
  nginx_http_requests_total:
    usage: counter
    labels:
      method: '"$request"'
      status: '$status'
  nginx_http_request_duration_seconds:
    usage: histogram
    buckets: [0.01, 0.05, 0.1, 0.5, 1, 5]
    labels:
      method: '"$request"'
      status: '$status'

Crie o serviço systemd para gerenciar o exportador:

sudo nano /etc/systemd/system/prometheus-nginxlog-exporter.service

Conteúdo do serviço:

[Unit]
Description=Prometheus Nginx Log Exporter
After=network.target

[Service]
User=root
ExecStart=/usr/local/bin/prometheus_nginxlog_exporter -config /etc/prometheus-nginxlog-exporter.yaml

[Install]
WantedBy=multi-user.target

Habilite e inicie o serviço:

sudo systemctl daemon-reload
sudo systemctl enable --now prometheus-nginxlog-exporter
sudo systemctl status prometheus-nginxlog-exporter

Passo 3: Configurando o Prometheus

Agora precisamos dizer ao Prometheus para coletar os dados expostos pelo nosso novo serviço. Edite o arquivo de configuração do Prometheus:

sudo nano /etc/prometheus/prometheus.yml

Adicione a seguinte seção em scrape_configs:

  - job_name: 'nginx-logs'
    static_configs:
      - targets: ['localhost:4040']

Recarregue o Prometheus:

sudo systemctl reload prometheus

Verifique se as métricas estão sendo geradas acessando http://seu-servidor:4040/metrics no navegador. Você deve ver linhas começando com nginx_http_requests_total.

Passo 4: Conectando Grafana e Criando o Dashboard

Acesse sua instância do Grafana. Vá em Configuration > Data Sources e adicione uma nova fonte de dados do tipo Prometheus. Insira a URL base (ex: http://localhost:9090) e salve.

Agora, crie um novo Dashboard:

1. Clique em + Create > Dashboard.
2. Clique em Add a new panel.

Métrica 1: Taxa de Requisições por Status HTTP

Este painel mostra a distribuição de respostas (200, 404, 500).

1. No query editor, selecione o banco de dados Prometheus.
2. Na query, insira:

rate(nginx_http_requests_total[5m])

Use a função rate para calcular a taxa por segundo nos últimos 5 minutos. Clique em Legend e defina o formato como {{status}} para agrupar os dados.

Métrica 2: Latência de Resposta (Histograma)

Para entender a performance, vamos visualizar a duração das requisições.

1. Crie um novo painel ou adicione ao existente.
2. Na query, insira:

rate(nginx_http_request_duration_seconds_sum[5m]) / rate(nginx_http_request_duration_seconds_count[5m])

Mude o tipo de gráfico para Time series. Isso mostrará a média de tempo de resposta ao longo do tempo.

Métrica 3: Top Endpoints Mais Lentos

Identifique quais rotas estão degradando a experiência do usuário.

topk(5, rate(nginx_http_request_duration_seconds_sum[5m]) / rate(nginx_http_request_duration_seconds_count[5m]))

Passo 5: Configurando Alertas via Telegram

Um dos maiores benefícios do Grafana é a capacidade de alertar fora da ferramenta. Vamos configurar um alerta para quando a taxa de erros HTTP (status >= 500) aumentar.

1. No painel que mostra os erros, clique na aba Alert.
2. Clique em Create Alert Rule.
3. Defina o critério: When expression A > 10 for 2m (onde A é a taxa de requisições com status 5xx).

Para notificações, vá em Configuration > Alerting > Contact Points.

1. Crie um novo ponto de contato do tipo Telegram.
2. Você precisará do token do seu Bot Telegram e do Chat ID. Se não tiver, crie um bot no @BotFather no Telegram.

Teste a notificação. Agora, se o Nginx começar a retornar muitos erros 500, sua equipe receberá uma mensagem instantânea no celular, muito mais rápido do que checar logs manualmente ou esperar um alerta genérico de uptime do Zabbix.

Integração com Outras Ferramentas de Monitoramento

É importante notar que esta solução não substitui, mas complementa ferramentas como Uptime Kuma e LibreNMS.

• Uptime Kuma: Continue usando para monitorar se o site está "no ar" (HTTP 200 básico). Ele é excelente para alertas de indisponibilidade total.
• LibreNMS / Zabbix: Mantenha-os monitorando a saúde do servidor (CPU, RAM, Disco, Load Average). Eles garantirão que o problema não seja infraestrutura, mas sim aplicação.

O Grafana com Prometheus preenche a lacuna entre "o servidor está ligado" e "o site está lento/errado". Ao consolidar dados de todas essas fontes no mesmo painel Grafana (usando múltiplas fontes de dados), você cria uma visão 360 graus da sua infraestrutura.

Conclusão

A criação de dashboards para logs de acesso Nginx usando Grafana e Prometheus eleva o nível de maturidade operacional da sua equipe. Você deixa de ser reativo (olhando logs após um incidente) para ser proativo (identificando tendências de latência e erros em tempo real).

Lembre-se de ajustar as métricas histogramas conforme a carga do seu servidor e de revisar periodicamente as regras de alerta para evitar fadiga de notificações. Com esta configuração, você está pronto para escalar sua observabilidade, mantendo o controle total sobre a experiência do usuário final.