veza/LOGGING.md

Gestion des Logs Veza

Organisation des Logs

Tous les logs de l'application Veza sont centralisés dans /var/log/veza/ avec une organisation par service.

Structure des Fichiers

/var/log/veza/
├── backend-api.log          # Tous les logs du backend API
├── backend-api-error.log    # Erreurs uniquement du backend API
├── redis.log                # Logs Redis
├── redis-error.log          # Erreurs Redis
├── db.log                   # Logs base de données
├── db-error.log             # Erreurs base de données
├── rabbitmq.log             # Logs RabbitMQ
├── rabbitmq-error.log       # Erreurs RabbitMQ
├── chat-server.log          # Logs du serveur de chat
├── chat-server-error.log    # Erreurs du serveur de chat
├── stream-server.log        # Logs du serveur de streaming
└── stream-server-error.log  # Erreurs du serveur de streaming

Rotation Automatique

Les logs sont automatiquement rotés avec la configuration suivante :

• Taille maximale : 100 MB par fichier
• Nombre de backups : 10 fichiers conservés
• Rétention : 30 jours
• Compression : Les anciens fichiers sont compressés en .gz

Les fichiers rotés sont nommés avec un suffixe numérique :

• backend-api.log.1.gz (le plus récent)
• backend-api.log.2.gz
• ...
• backend-api.log.10.gz (le plus ancien)

Configuration

Variables d'Environnement

Pour activer le logging vers /var/log/veza, configurez la variable d'environnement :

export LOG_DIR=/var/log/veza

Ajoutez cette ligne dans vos fichiers .env :

# Répertoire de logs
LOG_DIR=/var/log/veza

# Niveau de log (DEBUG, INFO, WARN, ERROR)
LOG_LEVEL=INFO

Permissions

Le répertoire /var/log/veza doit être accessible en écriture par l'utilisateur qui exécute les services.

Pour configurer les permissions :

sudo bash scripts/setup_logs.sh

Ou manuellement :

sudo mkdir -p /var/log/veza
sudo chown -R $USER:$USER /var/log/veza
sudo chmod 755 /var/log/veza

Utilisation

Visualiser les Logs

Le script view_logs.sh permet de visualiser facilement les logs :

# Voir les logs du backend API
bash scripts/view_logs.sh backend-api

# Voir uniquement les erreurs
bash scripts/view_logs.sh backend-api --errors

# Suivre les logs en temps réel
bash scripts/view_logs.sh backend-api --follow

# Filtrer par pattern
bash scripts/view_logs.sh backend-api -g "ERROR"

# Afficher les 100 dernières lignes
bash scripts/view_logs.sh backend-api -n 100

# Vue d'ensemble de tous les services
bash scripts/view_logs.sh all

Rotation Manuelle

Pour forcer la rotation des logs :

# Roter tous les logs
bash scripts/rotate_logs.sh all

# Roter uniquement le backend API
bash scripts/rotate_logs.sh backend-api

Commandes Utiles

# Voir la taille des fichiers de logs
du -h /var/log/veza/*.log

# Compter les erreurs dans les logs
grep -c "ERROR" /var/log/veza/backend-api.log

# Voir les logs en temps réel avec coloration
tail -f /var/log/veza/backend-api.log | grep --color=auto "ERROR\|WARN"

# Analyser les logs JSON (en production)
cat /var/log/veza/backend-api.log | jq '.level, .msg'

# Rechercher un pattern dans tous les logs
grep -r "user_id=123" /var/log/veza/

Format des Logs

Développement

En mode développement, les logs utilisent un format console lisible :

2026-01-03T22:54:47+01:00 INFO  Backend API démarré port=8080
2026-01-03T22:54:48+01:00 DEBUG Connexion Redis établie url=redis://localhost:6379

Production

En mode production, les logs sont en JSON structuré pour faciliter l'analyse :

{
  "level": "info",
  "ts": "2026-01-03T22:54:47.123Z",
  "caller": "api/main.go:66",
  "msg": "Backend API démarré",
  "port": 8080,
  "env": "production"
}

Monitoring et Alertes

Surveiller les Erreurs

Pour être alerté en cas d'erreurs critiques :

# Surveiller les fichiers d'erreurs
watch -n 10 'tail -n 20 /var/log/veza/*-error.log'

Agrégation de Logs (Optionnel)

Pour une installation en production, vous pouvez configurer l'agrégation vers un service externe (Loki, Elasticsearch, etc.) :

LOG_AGGREGATION_ENABLED=true
LOG_AGGREGATION_ENDPOINT=http://loki:3100/loki/api/v1/push
LOG_AGGREGATION_BATCH_SIZE=100
LOG_AGGREGATION_FLUSH_INTERVAL=5s

Docker

Configuration

Dans docker-compose.prod.yml, les logs sont montés via un volume partagé :

volumes:
  veza_logs:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /var/log/veza

services:
  backend:
    volumes:
      - veza_logs:/var/log/veza
    environment:
      - LOG_DIR=/var/log/veza

Accès aux Logs

# Voir les logs depuis le conteneur
docker exec veza_backend_prod tail -f /var/log/veza/backend-api.log

# Copier les logs vers l'hôte
docker cp veza_backend_prod:/var/log/veza ./logs-backup

Dépannage

Les logs ne sont pas créés

1. Vérifier les permissions :

   ls -ld /var/log/veza
   

2. Vérifier la variable d'environnement :

   echo $LOG_DIR
   

3. Vérifier les logs de démarrage du service

Espace disque insuffisant

1. Vérifier l'espace disponible :

   df -h /var/log/veza
   

2. Nettoyer les anciens logs :

   # Supprimer les logs de plus de 30 jours
   find /var/log/veza -name "*.gz" -mtime +30 -delete
   

3. Réduire la rétention dans la configuration de rotation

Performance

Si l'écriture des logs impacte les performances :

1. Vérifier que la rotation est activée
2. Augmenter le niveau de log (passer de DEBUG à INFO)
3. Activer le sampling en production (déjà configuré)

Sécurité

Logs Sensibles

Les secrets et données sensibles sont automatiquement filtrés des logs :

• Mots de passe
• Tokens JWT
• Clés API
• Informations de carte bancaire

Accès aux Logs

Limitez l'accès aux fichiers de logs :

# Permissions recommandées
chmod 640 /var/log/veza/*.log
chown $USER:$USER /var/log/veza/*.log

Support

Pour plus d'informations sur la configuration du logging, consultez :

• veza-backend-api/internal/logging/logger.go
• veza-chat-server/src/structured_logging.rs
• veza-stream-server/src/logging.rs (si applicable)