Golden Signals no NGINX

Este guia mostra como instrumentar qualquer servidor NGINX para expor os 4 Golden Signals — Throughput (taxa), Latência, Erros e Tráfego — utilizando os logs de acesso e um exporter leve baseado em logs.

---

✅ Pré-requisitos

• NGINX instalado e configurado
• Acesso ao arquivo /var/log/nginx/access.log
• Docker ou Docker Compose
• Prometheus ou OpenTelemetry Collector disponível
• Grafana para visualização (opcional, mas recomendado)

---

1️⃣ Configurar o log do NGINX

🔧 Etapa 1: Atualize o nginx.conf

Abra seu nginx.conf e adicione o seguinte formato de log:

log_format main '$remote_addr - $remote_user [$time_local] '
                '"$request" $status $body_bytes_sent '
                '"$http_referer" "$http_user_agent" "$http_x_forwarded_for" '
                'rt=$request_time '
                'urt=$upstream_response_time '
                'rlen=$request_length '
                'conn=$connection conn_reqs=$connection_requests';

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

💡 Isso adiciona campos essenciais para observabilidade: tempo de requisição, status, método, caminho, tamanho da resposta, entre outros.

🔄 Etapa 2: Reinicie o NGINX

sudo nginx -s reload

---

2️⃣ Subir o Exporter de Logs do NGINX

🔌 Opção A: Docker Compose

services:
  nginx_http_metrics:
    image: leonardozwirtes/nginx_http_metrics:latest
    container_name: nginx_http_metrics
    network_mode: host
    ports:
      - "2112:2112"
    environment:
      LOG_PATH: /var/log/nginx/access.log # Ou o caminho correto
    volumes:
      - /var/log/nginx:/var/log/nginx:ro
    restart: unless-stopped
    labels:
      org.label-schema.group: "monitoring"

docker-compose up -d

🛠️ Opção B: Docker direto

docker run -d \\
  -p 2112:2112 \\
  -v /var/log/nginx:/logs:ro \\
  -e LOG_PATH=/logs/access.log \\
  leonardozwirtes/nginx_http_metrics:latest

---

3️⃣ Configurar o Prometheus (alternativa)

Adicione ao seu prometheus.yml:

scrape_configs:
  - job_name: 'nginx_http_metrics'
    static_configs:
      - targets: ['<IP-OU-HOST-DO-EXPORTER>:2112']

Exemplo com Docker Compose (caso o Prometheus esteja na mesma rede):

scrape_configs:
  - job_name: 'nginx_http_metrics'
    static_configs:
      - targets: ['nginx_http_metrics:2112']

Depois reinicie o Prometheus.

---

4️⃣ ✅ (Melhor) Integrar com o OpenTelemetry Collector

Se você já usa OpenTelemetry — ou quer uma alternativa mais leve e flexível ao Prometheus — o Collector é a melhor opção.

Exemplo básico de configuração (otel-collector-config.yaml):

receivers:
  prometheus:
    config:
      scrape_configs:
        - job_name: 'nginx_http_metrics'
          static_configs:
            - targets: ['nginx_http_metrics:2112']

exporters:
  prometheusremotewrite:
    endpoint: <https://mimir.elvenobservability.com/api/v1/push>

service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [prometheusremotewrite]

Para rodar o Collector:

otelcol-contrib --config otel-collector-config.yaml

💡 Com o Collector, você pode enviar métricas não apenas para o Grafana, Tempo, Loki ou Prometheus — mas também para qualquer backend compatível com OTLP, com total controle de rotas, filtros e transformações.

---

5️⃣ Acessar o Endpoint de Métricas

Você pode testar o exporter com:

curl <http://localhost:2112/metrics>

Ou acessar no navegador:

<http://localhost:2112/metrics>

Você verá métricas como:

• http_requests_total
• http_duration_seconds_bucket
• http_errors_total
• http_traffic_bytes_total

---

6️⃣ 📊 Usar o Dashboard Pronto no Grafana

Criamos um dashboard pronto para visualizar todos os Golden Signals do NGINX:

👉 Dashboard Grafana: NGINX Golden Signals

Painéis incluídos:

Painel	Métrica
Requisições por segundo	rate(http_requests_total[1m])
Taxa de erro (4xx/5xx)	rate(http_errors_total[1m])
Latência P95	histogram_quantile(0.95, rate(http_duration_seconds_bucket[5m]))
Tráfego por rota	rate(http_traffic_bytes_total[1m])

💡 Você pode clonar ou personalizar o dashboard conforme necessário.

---

🔄 Normalização de Paths

Para evitar explosão de cardinalidade nas labels, estas regras são aplicadas:

• /user/123 → /user/:id
• /api/* → /api
• .php → /:php
• .env → /:env
• /admin/* → /admin
• Qualquer path com mais de 5 barras → /:complex

---

✅ Resumo

Etapa	Descrição
Configurar o log do NGINX	Adicionar log_format ao nginx.conf
Subir o exporter	Via Docker ou Docker Compose
Coletar as métricas	Via Prometheus ou Collector
Acessar métricas	http://localhost:2112/metrics
Visualizar no Grafana	Usar o Dashboard Golden Signals (link acima)

---

📌 Bônus: Cobertura dos Golden Signals

Sinal	Métrica
Throughput	http_requests_total
Latência	http_duration_seconds
Erros	http_errors_total
Tráfego	http_traffic_bytes_total