1) Instrumentação de APIs com métricas de alto valor

Neste primeiro projeto, eu demonstro como expor métricas relevantes de uma API. O objetivo é obter visibilidade sobre tráfego, latência e falhas, com métricas simples de consultar em PromQL e que não gerem alta cardinalidade.

// Exemplo mínimo em Go com Prometheus client
package main

import (
  "net/http"
  "github.com/prometheus/client_golang/prometheus"
  "github.com/prometheus/client_golang/prometheus/promhttp"
)

var (
  reqCount = prometheus.NewCounterVec(
    prometheus.CounterOpts{Name: "api_requests_total", Help: "Total de requisições"},
    []string{"method", "endpoint"},
  )
  reqDuration = prometheus.NewHistogramVec(
    prometheus.HistogramOpts{
      Name: "api_request_duration_seconds",
      Help: "Duração de requisições da API",
      Buckets: prometheus.DefBuckets,
    },
    []string{"endpoint"},
  )
)

func main() {
  prometheus.MustRegister(reqCount, reqDuration)

  http.Handle("/metrics", promhttp.Handler())

  http.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
    timer := prometheus.NewTimer(reqDuration.WithLabelValues("/hello"))
    defer timer.ObserveDuration()

    reqCount.WithLabelValues(r.Method, "/hello").Inc()
    w.Write([]byte("OK"))
  })

  http.ListenAndServe(":8080", nil)
}

Dicas: exponha métricas estáveis, evite alta cardinalidade desnecessária e use labels com consistência entre serviços.

2) Exporter personalizado para fontes externas

Eu crio exporters para coletar métricas de sistemas legados ou serviços não instrumentados, transformando-as para o formato Prometheus. Assim, a camada de coleta fica simples e uniformizada.

# Exporter simples em Python com prometheus_client
from prometheus_client import start_http_server, Gauge
import time
import random

g_api_latency = Gauge('external_api_latency_seconds', 'Latência da API externa', ['service'])

def collect():
    while True:
        # simula coleta de métricas de uma fonte externa
        g_api_latency.labels(service='payments').set(random.random() * 0.5)
        g_api_latency.labels(service='users').set(random.random() * 0.3)
        time.sleep(1)

if __name__ == '__main__':
    start_http_server(8000)
    collect()

O exporter expõe /metrics na porta configurada, que é consumida pelo Prometheus. Planeje o scraping interval adequado para o seu cenário.

3) Alertas com Prometheus e Alertmanager

Para eu manter a confiabilidade, eu defino regras de alerta que detectam picos de latência, falhas ou queda de disponibilidade. O Alertmanager então roteia notificações de forma controlada para equipes, com deduplicação e silenciamento quando necessário.

# Regra de alerta Prometheus (alerting rules)
groups:
- name: api.rules
  rules:
  - alert: HighRequestLatency
    expr: (rate(api_request_duration_seconds_sum[5m]) / rate(api_request_duration_seconds_count[5m])) > 0.5
    for: 10m
    labels:
      severity: critical
    annotations:
      summary: "Latência de API alta"
      description: "Latência média excedeu 0.5s nos últimos 5 minutos. Endpoint: {{ $labels.endpoint }}"

# Configuração básica do Alertmanager (receivers/routes)
global:
  resolve_timeout: 5m

route:
  receiver: 'ops-team'
  group_by: ['alertname', 'service']

receivers:
- name: 'ops-team'
  email_configs:
  - to: 'ops-team@example.com'
    from: 'alerts@example.com'
    smarthost: 'smtp.example.com:587'
    auth_username: 'alerts@example.com'
    auth_password: 'SEU-PASS'
    auth_identity: 'alerts@example.com'

Dicas: comece com notificações simples por e-mail ou Slack para validar o fluxo. Ajuste expr e for para reduzir falsos positivos.

4) Dashboards com Grafana e consultas PromQL

Por fim, eu monto dashboards que respondem perguntas práticas: qual é a latência 95% por endpoint? qual serviço consome mais recursos? Painéis com consultas PromQL bem definidas ajudam a tomar decisões rápidas.

# Exemplo de consultas PromQL usadas em painéis Grafana

# Latência p95 por endpoint
histogram_quantile(0.95, rate(api_request_duration_seconds_bucket[5m])) by (endpoint)

# Taxa de requisições por método
rate(api_requests_total[1m])

# Erros por endpoint
sum(rate(api_requests_total{status!~"2.."}[5m])) by (endpoint)

Dicas de layout: detalhe títulos descritivos, alinhe métricas por serviço e ofereça filtros de time range para comparação histórica rápida.