Stronger Daily
Articolo

Curl per monitoraggio KPI body: come misurare i KPI nel body delle API con curl

A man doing a kickbox kick in a gym
Foto Boris Izmaylov su Unsplash

Curl per monitoraggio KPI body: come misurare i KPI nel body delle API con curl

Il monitoraggio dei KPI (Key Performance Indicator) è una pratica fondamentale per garantire prestazioni affidabili delle API e dei servizi web. Tra gli strumenti più accessibili e potenti c’è curl, il client HTTP a riga di comando. In questo articolo vedremo come utilizzare curl per monitorare KPI contenuti nel body della risposta, come estrarli, come misurare la performance delle chiamate e come automatizzare tutto in modo robusto e sicuro.

Introduzione al concetto: KPI nel body e perché curl è una scelta vincente

I KPI legati alle API possono trovarsi in diverse forme all’interno del body JSON o XML della risposta: valori numerici, percentuali, timestamp o indicatori di stato. Ecco perché curl, insieme a strumenti di parsing come jq, diventa una soluzione pratica per:

  • Interrogare endpoint KPI-friendly in modo semplice e ripetibile.
  • Misurare parametri di performance come tempi di risposta e latenze, oltre ai contenuti del body (es. valore del KPI).
  • Automatizzare controlli periodici e allarmi, integrando i dati in dashboard o workflow di incidente.

Questo articolo si concentra sull’utilizzo di curl per estrarre e monitorare KPI presenti nel body della risposta, fornendo esempi concreti, best practice e script pratici.

Strumenti essenziali: curl, jq e tanto altro

  • curl: per inviare richieste HTTP e controllare l’header, il corpo e i tempi di risposta.
  • jq: per estrarre valori dal body JSON in modo affidabile.
  • un sistema di automazione (cron, systemd timers) per eseguire controlli periodici.
  • strumenti di logging (file di log, stdout/stderr) per conservare i dati raccolti.
  • eventuale integrazione con strumenti di allerta (email, Slack, PagerDuty, altre piattaforme) in base agli alert sui KPI.

Riteniamo importante avere jq disponibile per parse JSON. Se l’endpoint restituisce altre strutture (es. XML), si può utilizzare strumenti adeguati (xmllint, xmlstarlet), ma JSON resta lo scenario più comune.

Tecniche chiave: come estrarre KPI dal body e misurare la performance

Estrazione dei KPI dal body con curl e jq

Esempio tipico: un endpoint GET restituisce un body JSON come:

{ "kpi": { "uptime": 99.95, "latency_ms": 123, "error_rate": 0.01, "active_users": 512 } }

Per estrarre i valori nel body e registrarli insieme a metriche di performance, puoi combinare curl con jq.

  • curl recupera la risposta e la salva su un file, mentre -w (write-out) stampa metriche aggiuntive sullo stdout.
  • jq estrae i campi dal file salvato.

Esempio di comando:

curl -sS -o response.json -w "HTTP_CODE=%{http_code} TIME_TOTAL=%{time_total}s\n" https://api.example.com/kpi | jq '.kpi' response.json

In questo modo hai:

  • HTTP_CODE: codice HTTP della risposta.
  • TIME_TOTAL: tempo totale della richiesta (secondi).
  • Il contenuto del body richiesto viene trasformato da jq in metriche utili.

Un approccio leggermente più strutturato, utile per registrare sia i KPI che i tempi, è utilizzare una variabile di output:

OUTPUT=$(curl -sS -o response.json -w "HTTP_CODE=%{http_code} TIME_TOTAL=%{time_total}\n" https://api.example.com/kpi) HTTP_CODE=$(echo "$OUTPUT" | grep -o "HTTP_CODE=[0-9]" | cut -d'=' -f2) TIME_TOTAL=$(echo "$OUTPUT" | grep -o "TIME_TOTAL=[0-9.]" | cut -d'=' -f2) KPI_VALUE=$(jq '.kpi' < response.json)

echo "[$(date '+%F %T')] HTTP_CODE=$HTTP_CODE, TIME_TOTAL=${TIME_TOTAL}s, KPI=$KPI_VALUE" >> kpi.log

Questo flusso permette di avere una riga di log leggibile con timestamp, codice HTTP, tempo di esecuzione e valore del KPI estratto dal body.

Misurare la performance di curl: metriche utili

Nel monitoraggio dei KPI, le metriche di performance di curl sono essenziali. Alcune opzioni utili includono:

  • -sS: silenzia la barra di progresso, mostra solo errori se presenti.
  • -f o --fail: falla al ritorno di codice HTTP >= 400 (utile per non considerare risposte non valide come successi).
  • -o FILE: scrive il body della risposta in FILE (per jq o analisi successiva).
  • -D -: stampa gli header della risposta se necessario.
  • -w: write-out per stampare metriche personalizzate, ad es. HTTP_CODE, time_namelookup, time_connect, time_starttransfer, time_total, size_download, ecc.

Esempio di uso avanzato con more metriche:

curl -sS -o response.json -D - -w "HTTP_CODE=%{http_code} DNS_TIME=%{time_namelookup} CONNECT_TIME=%{time_connect} START_TIME=%{time_starttransfer} TOTAL_TIME=%{time_total}\n" https://api.example.com/kpi

Questa variante fornisce un quadro completo dei tempi di ogni fase della richiesta, utile per analizzare collo di bottiglia a livello di rete o di server.

Elaborazione dei KPI nel body con jq (esempio JSON)

Dopo aver salvato la risposta in response.json, puoi estrarre KPI specifici con jq. Ad esempio:

  • Valore di uptime: jq '.kpi.uptime' response.json

  • Latency: jq '.kpi.latency_ms' response.json

  • Report combinato (log integrato): echo "$(date '+%F %T'), HTTP_CODE=$HTTP_CODE, TIME_TOTAL=${TIME_TOTAL}s, LATENCY_MS=$(jq '.kpi.latency_ms' response.json), UPTIME=$(jq '.kpi.uptime' response.json)" >> kpi.log

Questa separazione tra ottenimento della risposta (curl) e parsing del contenuto (jq) migliora robustezza e manutenibilità.

Automazione: monitoraggio continuo e allarmi

Per avere un monitoraggio continuo, esegui periodicamente i comandi di cui sopra usando cron (Linux/macOS) o systemd timers.

Esempio di crontab per eseguire ogni 5 minuti:

*/5 * * * * /path/to/monitor_kpi.sh

Dentro lo script, puoi:

  • Appendere log su un file dedicato (es. kpi.log) con timestamp, codice HTTP, tempo totale e KPI.
  • Generare allarmi: se HTTP_CODE è diverso da 200, o se TIME_TOTAL supera una soglia (es. > 2.0 secondi), invia una notifica via email, Slack o PagerDuty.
  • Inviare metriche a un sistema di monitoraggio: puoi esporre i dati come metriche plaintext in un endpoint locale o inviarli a Prometheus Pushgateway, oppure inviarli a un SIEM o a un sistema di logging centralizzato.

Esempio di pseudo-script di allarme:

if [ "$HTTP_CODE" -ne 200 ]; then echo "ALERT: KPI endpoint returned code $HTTP_CODE" | mail -s "KPI Alert" admin@example.com fi

if (( $(echo "$TIME_TOTAL > 2.0" | bc -l) )); then echo "ALERT: KPI endpoint latency ${TIME_TOTAL}s" | mail -s "KPI Latency Alert" admin@example.com fi

Questo approccio consente di avere una visibilità immediata sui problemi di disponibilità o prestazioni, e di reagire rapidamente.

Best practices: sicurezza, affidabilità e qualità dei dati

  • Gestisci in modo sicuro le credenziali: se l’endpoint richiede autorizzazioni, usa header di autenticazione appropriati (es. Bearer token) e non incollarli nei log. Esempio: curl -sS -H "Authorization: Bearer $TOKEN" -o response.json ...

  • Evita di esporre dati sensibili nei log: filttra o anonimizza valori nel log se contengono dati sensibili.

  • Usa --fail per ignorare risposte HTTP di errore senza processare il body.

  • Controlla la dimensione del body: se l’endpoint potrebbe restituire payload molto grande, usa -H "Accept: application/json" e considera limiti di memoria.

  • Rendi robusta la gestione degli errori: controlla HTTP_CODE, gestisci casi di body vuoto o di chiavi mancanti (verifica con jq prima di usarlo).

  • Documenta lo schema KPI dell’endpoint: avere una definizione chiara di quali KPI sono presenti nel body facilita manutenzione e integrazione con altri team.

  • Testa regolarmente lo script di monitoraggio in un ambiente di staging per evitare falsi allarmi in produzione.

Esempio pratico: script di monitoraggio completo (snack-size)

Di seguito un esempio di script Bash essenziale, che documenta l’uso di curl per misurare tempi e KPI dal body, salva un log e genera una semplice alert via log.

#!/bin/bash URL="https://api.example.com/kpi" OUT="response.json" LOG="kpi.log"

OUTPUT=$(curl -sS -o "$OUT" -w "HTTP_CODE=%{http_code} TIME_TOTAL=%{time_total}\n" "$URL") HTTP_CODE=$(echo "$OUTPUT" | grep -o "HTTP_CODE=[0-9]" | cut -d'=' -f2) TIME_TOTAL=$(echo "$OUTPUT" | grep -o "TIME_TOTAL=[0-9.]" | cut -d'=' -f2)

KPI_VALUE=$(jq '.kpi' "$OUT" 2>/dev/null || echo "null")

LOG_LINE="$(date '+%F %T'), HTTP_CODE=$HTTP_CODE, TIME_TOTAL=${TIME_TOTAL}s, KPI=$KPI_VALUE" echo "$LOG_LINE" >> "$LOG"

if [ "$HTTP_CODE" != "200" ]; then echo "ALERT: KPI endpoint returned HTTP_CODE=$HTTP_CODE" >> "$LOG" fi

exit 0

Questo script è volutamente essenziale: può essere esteso per inviare notifiche o esportare metriche in formati compatibili con strumenti di monitoraggio.

Riepilogo

  • curl è uno strumento ideale per monitorare KPI presenti nel body delle API, consentendo di estrarre valori di KPI con jq e di misurare le performance della richiesta tramite -w.
  • Integrare curl con jq facilita l’analisi dei dati, trasformando risposte JSON in metriche concrete da monitorare nel tempo.
  • Automatizzare con cron o timer consente controlli regolari, logging persistente e allarmi proattivi in caso di anomalie (HTTP errori, latenze eccessive).
  • Adotta best practice di sicurezza e robustezza: gestione sicura delle credenziali, gestione degli errori HTTP, logging responsabile e validazione dello schema KPI.

Seguendo queste linee guida, potrai ottenere una pipeline semplice ma affidabile per monitorare i KPI nel body delle API, con report, allarmi e possibilità di integrazione con le tue dashboard di monitoraggio. Se vuoi, posso fornirti uno script completo e pronto all’uso adattato al tuo endpoint KPI specifico (URL, schema JSON, soglie di allarme).