Prometheus da zero: scraping, PromQL e alerting — Guida operativa • Meteora Web Agency

Il tuo server va in down alle 3 di notte e te ne accedi alle 9. Il tuo e-commerce perde conversioni da ore e tu non lo sai. Questo è il problema che Prometheus risolve: non un cruscotto carino, ma un sistema che raccoglie metriche, le interroga in tempo reale e ti avvisa prima che il danno sia fatto. Noi di Meteora Web lo abbiamo integrato in diverse architetture per clienti con esigenze di produzione. Ed è esattamente quello che ti serve per smettere di inseguire i problemi e iniziare a prevenirli.

Perché Prometheus e non altro?

Prometheus è un sistema open source di monitoring e alerting nato in SoundCloud e oggi parte della CNCF. Il suo punto di forza è il modello pull: lo stesso Prometheus interroga periodicamente i target (esportatori, applicazioni) per raccogliere metriche. Questo significa che non devi configurare agenti su ogni macchina che inviano dati; è Prometheus che decide cosa e quando campionare. Inoltre le metriche sono etichettate con labels, una dimensione che rende le query estremamente flessibili. Perché ti interessa? Se hai un cluster Kubernetes, Prometheus è lo standard de facto. Anche senza K8s, per qualsiasi stack Linux, applicazioni web o API, Prometheus è la scelta più solida per chi vuole controllo e scalabilità, non un "black box" SaaS con costi che crescono col volume.

Errori comuni all’inizio

Pensare che Prometheus sia un dashboard (non lo è; Grafana lo è).
Non capire il modello pull e configurarlo per ricevere push (esiste Pushgateway per casi eccezionali, ma non è la norma).
Saltare la progettazione delle labels: troppe o troppo poche rendono le query inutili.

Cominciamo: installazione e primo scrape

Scarica l'ultima release dal sito ufficiale. La configurazione di base è un file YAML prometheus.yml.

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

Avvia con ./prometheus --config.file=prometheus.yml. Visita http://localhost:9090. Hai già i dati: Prometheus espone le proprie metriche. Questo è il primo passo verso il monitoring reale.

Cosa fare subito

Vai su /targets nella UI di Prometheus e verifica che lo stato sia UP. Se sì, hai un sistema funzionante. Ora aggiungi un target reale.

Scraping con exporter: esempi reali

Prometheus non capisce nativamente qualsiasi formato; ha bisogno di un exporter che esponga le metriche nel suo formato (text-based). Per Linux il più comune è node_exporter. Scarica, estrai e avvia:

wget https://github.com/prometheus/node_exporter/releases/latest/download/node_exporter-*.tar.gz
tar xvf node_exporter-*.tar.gz
cd node_exporter-*
./node_exporter

Ora node_exporter è in ascolto sulla porta 9100. Aggiungilo al tuo prometheus.yml:

scrape_configs:
  - job_name: 'node'
    static_configs:
      - targets: ['localhost:9100']

Riavvia Prometheus o invia SIGHUP. In un minuto avrai metriche come node_cpu_seconds_total, node_memory_MemAvailable_bytes. Questo è l'abc: ogni servizio (MySQL, Nginx, PostgreSQL, Redis) ha il suo exporter. Li trovi sul sito ufficiale di Prometheus o su GitHub.

Metriche personalizzate da un'applicazione

Se sviluppi in Python, Go, Java, puoi esporre metriche direttamente usando le librerie client. Esempio in Python con prometheus_client:

from prometheus_client import start_http_server, Counter
import random
import time

c = Counter('http_requests_total', 'Total HTTP requests', ['method', 'endpoint'])

if __name__ == '__main__':
    start_http_server(8000)
    while True:
        c.labels(method='GET', endpoint='/api/ordini').inc()
        time.sleep(0.5)

Configura uno scrape su localhost:8000. Ora ogni richiesta alla tua app viene contata. Questo ti permette di monitorare business metriche: ordini, visualizzazioni, errori.

PromQL: il linguaggio per interrogare i dati

PromQL (Prometheus Query Language) è il cuore analitico. Non serve un database SQL; si basa su espressioni vettoriali e time series. Ecco i concetti essenziali.

Metriche e labels

Una metrica è un nome con un insieme di labels. Esempio: http_requests_total{method="GET", endpoint="/home"}. L'identificativo unico è la combinazione nome+labels. PromQL opera su serie temporali.

Operazioni di base

node_memory_MemAvailable_bytes restituisce il valore istantaneo per ogni serie.
rate(node_cpu_seconds_total[5m]) calcola la media di incremento per secondo su una finestra di 5 minuti. Usato per CPU, richieste al secondo.
irate per cambiamenti rapidi, ma rumoroso.
increase(node_network_receive_bytes_total[1h]) incremento assoluto su 1 ora.

Filtrare e aggregare

node_cpu_seconds_total{job="node",mode="user"} filtra per label. Per aggregare: sum by (instance) (rate(node_cpu_seconds_total[5m])).

Esempio pratico: alert per alta CPU

Questa query restituisce l'utilizzo CPU medio per istanza negli ultimi 5 minuti:

100 - (avg by (instance)(rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)

Se lo usiamo in un alert, inviamo notifica quando supera l'80%.

Alerting con Alertmanager

Raccogliere metriche è inutile se non si interviene. Prometheus valuta regole di alerting e invia eventi ad Alertmanager, che gestisce deduplicazione, raggruppamento e routing verso canali (email, Slack, PagerDuty, Telegram).

Regole di alerting

Creiamo un file rules.yml:

groups:
  - name: node_alerts
    rules:
      - alert: HighCpuUsage
        expr: 100 - (avg by (instance)(rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 80
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "CPU alta su {{ $labels.instance }}"
          description: "CPU usage at {{ $value }}% per oltre 5 minuti."

Aggiungi rule_files: ['rules.yml'] in prometheus.yml. Riavvia.

Configurare Alertmanager

Scarica alertmanager, configura ad esempio per inviare a Slack tramite webhook. Ecco un estratto di alertmanager.yml:

global:
  slack_api_url: 'https://hooks.slack.com/services/...'

route:
  receiver: 'slack'
receivers:
  - name: 'slack'
    slack_configs:
      - channel: '#alerts'
        title: '{{ .GroupLabels.alertname }}'
        text: '{{ .CommonAnnotations.description }}'

Avvia alertmanager (porta 9093) e configura Prometheus per inviargli alert: nel prometheus.yml aggiungi alerting: { alertmanagers: [ - static_configs: [ targets: ['localhost:9093'] ] ] }. Ora i tuoi alert arrivano in Slack.

Buone pratiche e sicurezza

Noi vediamo spesso configurazioni fatte male: metriche sensibili esposte, alert troppo frequenti, nessuna retention policy. Ecco cosa facciamo noi nei progetti reali:

Retention: default 15 giorni. Imposta --storage.tsdb.retention.time=30d per archivi più lunghi.
Accesso: Prometheus non ha autenticazione nativa. Metti un reverse proxy (Nginx) con basic auth o utilizza un proxy di terze parti.
Labels cardinalità: evita label con valori unici per ogni richiesta (es. user_id). Prometheus esplode.
Job name: usa nomi descrittivi, non job1.
Alert fatigue: usa for: 5m per evitare falsi allarmi. Suddividi in canali diversi per gravità.

Cosa fare adesso

Installa Prometheus e node_exporter su almeno un server o locale. Verifica i target.
Scrivi due regole di alert: una per CPU, una per spazio disco (node_filesystem_avail_bytes).
Collega Alertmanager a un canale Slack (o Telegram) e verifica che arrivi la notifica.
Esplora PromQL: usa la console di Prometheus per creare un grafico delle richieste HTTP al minuto per endpoint.
Programma un controllo mensile della cardinalità delle labels per evitare overflow.

Se hai bisogno di supporto su architetture complesse o integrazioni personalizzate, noi di Meteora Web accompagniamo aziende dalla configurazione iniziale fino al monitoring enterprise. Il tuo sito merita di essere sempre reattivo, non è solo una questione di tecnologia: è il tuo fatturato.