Runbook: Tasso di Errore Elevato

Severita: Warning Alert Prometheus: HighErrorRate

Descrizione

Questo alert si attiva quando il tasso di errore di un servizio Moleculer supera il 5% delle richieste totali in una finestra di 5 minuti. Gli errori includono eccezioni non gestite, timeout, errori di validazione, fallimenti di connessione al database e attivazione dei circuit breaker.

Regola Prometheus:

(rate(moleculer_request_error_total{namespace="pos-enterprise"}[5m])
/ rate(moleculer_request_total{namespace="pos-enterprise"}[5m]))
> 0.05

Impatto

• Degradazione del servizio: una percentuale significativa di richieste fallisce, gli utenti ricevono errori.
• Circuit breaker aperti: se il tasso supera la soglia del circuit breaker (default 50%), il servizio viene isolato.
• Retry storm: i client retentano le richieste fallite, amplificando il carico.
• Dati inconsistenti: operazioni di scrittura parzialmente completate possono lasciare dati in stato inconsistente.
• Impatto business: ordini persi, pagamenti non registrati, stampe mancanti.

Diagnosi

1. Identificare i servizi con errori elevati

# Grafana: tasso di errore per servizio
sum by (service) (rate(moleculer_request_error_total{namespace="pos-enterprise"}[5m]))
/ sum by (service) (rate(moleculer_request_total{namespace="pos-enterprise"}[5m]))

# Top 10 azioni con piu errori
topk(10,
  sum by (action) (rate(moleculer_request_error_total{namespace="pos-enterprise"}[5m]))
)

2. Analizzare i tipi di errore

# Log degli errori recenti dal gateway
kubectl logs deployment/api-gateway -n pos-enterprise --tail=200 | \
  grep -i "error\|ERR\|failed" | tail -30

# Log da un servizio specifico
kubectl logs deployment/orders-node -n pos-enterprise --tail=200 | \
  grep -i "error\|ERR\|failed" | tail -30

3. Classificare gli errori Moleculer

I tipi di errore piu comuni nella piattaforma:

Errore Moleculer	Codice HTTP	Causa tipica
ValidationError	422	Parametri invalidi
ServiceNotFoundError	404	Servizio non registrato in NATS
ServiceNotAvailableError	503	Tutte le istanze down
RequestTimeoutError	504	Azione non risponde in tempo
RequestRejectedError	503	Bulkhead pieno, coda esaurita
MaxCallLevelError	500	Chiamate ricorsive eccessive
MoleculerError	500	Errore generico applicativo
ServiceSchemaError	500	Schema servizio malformato

# Contare gli errori per tipo
kubectl logs deployment/api-gateway -n pos-enterprise --since=30m | \
  grep -oP '"type":"[^"]+"' | sort | uniq -c | sort -rn

4. Verificare lo stato dei circuit breaker

# Metriche Moleculer via endpoint interno
curl -s https://platform.sellogic.cloud/api/\$node/health | jq '.client.circuitBreaker'

# Lista dei servizi con circuit breaker aperto
curl -s https://platform.sellogic.cloud/api/\$node/list | jq '
  .[] | select(.circuits? | length > 0) | {hostname, circuits}
'

# Circuit breaker aperti (Grafana)
moleculer_circuit_breaker_opened_total{namespace="pos-enterprise"}

5. Verificare la connettivita al database

# Test connessione MongoDB
kubectl exec deployment/orders-node -n pos-enterprise -- \
  node -e "
    const mongoose = require('mongoose');
    mongoose.connect(process.env.MONGO_URI).then(() => {
      console.log('MongoDB: OK');
      return mongoose.connection.db.admin().ping();
    }).then(r => {
      console.log('Ping:', JSON.stringify(r));
      process.exit(0);
    }).catch(e => {
      console.error('MongoDB error:', e.message);
      process.exit(1);
    });
  "

6. Verificare lo stato di Redis

kubectl run redis-check --rm -it --image=redis:7-alpine -n pos-enterprise -- \
  redis-cli -u "$REDIS_URL" info stats | grep -E "rejected_connections|keyspace_misses|evicted_keys"

7. Verificare i retry esauriti

# Cercare nei log i retry falliti
kubectl logs deployment/api-gateway -n pos-enterprise --since=15m | \
  grep -c "retry"

Risoluzione

Causa: Errori di connessione MongoDB

# Verificare lo stato del cluster MongoDB Atlas
# Dashboard: https://cloud.mongodb.com

# Se ci sono problemi di rete, verificare la whitelist IP
# Se il cluster e sovraccarico, verificare le metriche Atlas

# Restart rolling dei servizi per rinfrescare le connessioni
kubectl rollout restart deployment orders-node -n pos-enterprise
kubectl rollout restart deployment products-node -n pos-enterprise

Causa: Timeout (RequestTimeoutError)

# Aumentare temporaneamente il timeout per il servizio
kubectl set env deployment/<DEPLOY_NAME> -n pos-enterprise \
  MOL_REQUEST_TIMEOUT=30000

# Verificare se ci sono query lente
kubectl exec deployment/orders-node -n pos-enterprise -- \
  node -e "
    const m = require('mongoose');
    m.connect(process.env.MONGO_URI).then(async () => {
      const profiler = await m.connection.db.command({profile: -1});
      console.log('Profiler level:', profiler.was);
      const slow = await m.connection.db.collection('system.profile')
        .find({}).sort({ts: -1}).limit(5).toArray();
      slow.forEach(q => console.log(q.millis + 'ms -', q.ns, JSON.stringify(q.command).substring(0,100)));
      process.exit(0);
    });
  "

Causa: Circuit breaker aperti

# I circuit breaker si resettano automaticamente dopo halfOpenTime (default 10s).
# Se il problema sottostante e risolto, attendere il reset automatico.

# Per forzare il reset, riavviare il nodo
kubectl rollout restart deployment <DEPLOY_NAME> -n pos-enterprise

Causa: Errori di validazione massivi

Se il tasso di errore e causato da ValidationError (422):

# Verificare i log per capire quali parametri sono invalidi
kubectl logs deployment/api-gateway -n pos-enterprise --since=15m | \
  grep "ValidationError" | head -20

# Probabile causa: aggiornamento client con schema incompatibile
# Verificare la versione del client che invia le richieste
kubectl logs deployment/api-gateway -n pos-enterprise --since=15m | \
  grep "User-Agent" | sort | uniq -c

Causa: ServiceNotAvailableError

# Verificare quali servizi hanno 0 istanze
curl -s https://platform.sellogic.cloud/api/\$node/services | jq '
  .[] | select(.nodes | length == 0) | .name
'

# Riavviare il deployment del servizio mancante
kubectl rollout restart deployment <DEPLOY_NAME> -n pos-enterprise

Mitigazione: ridurre il carico

# Abilitare rate limiting sul gateway (se non attivo)
# Ridurre le repliche dei batch job
kubectl scale deployment scheduler-node -n pos-enterprise --replicas=1

# Scalare i servizi sotto pressione
kubectl scale deployment orders-node -n pos-enterprise --replicas=3

Prevenzione

• Monitoraggio granulare: alert separati per errori 4xx (client) e 5xx (server).
• Retry policy ottimizzata: configurare retry con backoff esponenziale e jitter.
• Bulkhead per servizio: limitare la concorrenza per evitare cascate.
• Graceful degradation: i servizi devono fallire in modo prevedibile (fallback, cache stale).
• Canary deploy: introdurre cambiamenti gradualmente per individuare regressioni.

# Alert separato per errori server (5xx)
(rate(moleculer_request_error_total{namespace="pos-enterprise", code=~"5.."}[5m])
/ rate(moleculer_request_total{namespace="pos-enterprise"}[5m]))
> 0.02

# Alert per errori client (potenziale bug nel frontend)
(rate(moleculer_request_error_total{namespace="pos-enterprise", code=~"4.."}[5m])
/ rate(moleculer_request_total{namespace="pos-enterprise"}[5m]))
> 0.10

• Dashboard dedicata: creare un pannello Grafana con error budget (SLO 99.5% disponibilita).

Escalation

Livello	Condizione	Contatto
L1 - Ops	Error rate 5-10%, singolo servizio	Monitorare, verificare logs
L2 - Dev	Error rate > 10%, errori applicativi	Team Dev (Slack #pos-dev)
L2 - Ops	Error rate > 5%, causa infrastrutturale	DevOps - verificare DB/NATS/Redis
L3 - All	Error rate > 20%, multipli servizi	Incident call - tutti i team

Tempo massimo di risposta: 15 minuti. Se accompagnato da alert di servizi down, trattare come Critical.