Monitoring e logging¶

Health check¶

Tutti i servizi backend espongono GET /health. Gli healthcheck di Docker Compose interrogano questo endpoint e riavviano automaticamente un servizio se non risponde.

curl http://localhost:8000/health   # gateway
curl http://localhost:8001/health   # auth
curl http://localhost:8002/health   # catalog
curl http://localhost:8003/health   # ai (servizio opzionale)

Risposta attesa: {"status": "ok"}

Cosa cercare all'avvio¶

Dopo un deploy, controlla i log per queste righe che confermano un avvio sano:

# auth-service, catalog-service, ai-service (ognuno migra il proprio schema
# nel database condiviso "jinbocho"):
INFO  [alembic] Running upgrade -> <revision>, <description>
INFO  [alembic] Done.
INFO:     Application startup complete.

# api-gateway (nessun database):
INFO:     Application startup complete.

# Qualsiasi servizio — segnale negativo:
ERROR - Connection refused
sqlalchemy.exc.OperationalError: (asyncpg.exceptions.InvalidPasswordError)

Se le righe di Alembic mancano o mostrano errori, DATABASE_URL è configurato in modo errato — vedi Troubleshooting.

Logging dell'applicazione¶

I log vengono scritti su stdout, visibili con:

docker compose -f docker/docker-compose.all.yml --env-file .env logs -f              # tutti i servizi
docker compose -f docker/docker-compose.all.yml --env-file .env logs -f auth-service # un solo servizio

Livello	Quando
`INFO`	Avvio del servizio, completamento migrazioni, riepiloghi delle richieste
`WARNING`	Problemi non critici (es. ISBN non trovato in nessuna fonte)
`ERROR`	Eccezioni, richieste fallite, errori del database

Monitoraggio del server (Netdata)¶

Le metriche host + per-container (CPU/RAM/disco/rete) sono disponibili tramite un unico container Netdata — nessun account esterno, nessun segreto da configurare.

Disabilitato di default. Abilitalo all'installazione (--netdata-enabled true su setup-vps-community.sh) o in seguito con:

docker compose -f docker/docker-compose.all.yml --profile observability up -d

La dashboard è legata solo a 127.0.0.1:19999 — mai esposta pubblicamente. Raggiungila via SSH:

ssh -L 19999:localhost:19999 <utente>@<host>

Poi apri http://localhost:19999 in locale.