stripstream/docs/cache-debug.md

Debug du Cache

Guide pour debugger le système de caching de StripStream.

Activation des logs de cache

Variable d'environnement

Activez les logs détaillés du cache serveur avec :

CACHE_DEBUG=true

Configuration

Développement (docker-compose.dev.yml)

environment:
  - CACHE_DEBUG=true

Production (.env)

CACHE_DEBUG=true

Format des logs

Les logs de cache apparaissent dans la console serveur avec le format suivant :

Cache HIT (donnée valide)

[CACHE HIT] home-ongoing | HOME | 0.45ms

• ✅ Donnée trouvée en cache
• ✅ Donnée encore valide (pas expirée)
• ⚡ Retour immédiat (très rapide)

Cache STALE (donnée expirée)

[CACHE STALE] home-ongoing | HOME | 0.52ms

• ✅ Donnée trouvée en cache
• ⚠️ Donnée expirée mais toujours retournée
• 🔄 Revalidation lancée en background

Cache MISS (pas de donnée)

[CACHE MISS] home-ongoing | HOME

• ❌ Aucune donnée en cache
• 🌐 Fetch normal depuis Komga
• 💾 Mise en cache automatique

Cache SET (mise en cache)

[CACHE SET] home-ongoing | HOME | 324.18ms

• 💾 Donnée mise en cache après fetch
• 📊 Temps total incluant le fetch Komga
• ✅ Prochaines requêtes seront rapides

Cache REVALIDATE (revalidation background)

[CACHE REVALIDATE] home-ongoing | HOME | 287.45ms

• 🔄 Revalidation en background (après STALE)
• 🌐 Nouvelle donnée fetched depuis Komga
• 💾 Cache mis à jour pour les prochaines requêtes

Erreur de revalidation

[CACHE REVALIDATE ERROR] home-ongoing: Error: ...

• ❌ Échec de la revalidation background
• ⚠️ Cache ancien conservé
• 🔄 Retry au prochain STALE

Types de cache

Les logs affichent le type de TTL utilisé :

Type	TTL	Usage
DEFAULT	5 min	Données génériques
HOME	10 min	Page d'accueil
LIBRARIES	24h	Bibliothèques
SERIES	5 min	Séries
BOOKS	5 min	Livres
IMAGES	7 jours	Images

Exemple de session complète

# Première requête (cache vide)
[CACHE MISS] home-ongoing | HOME
[CACHE SET] home-ongoing | HOME | 324.18ms

# Requête suivante (cache valide)
[CACHE HIT] home-ongoing | HOME | 0.45ms

# 10 minutes plus tard (cache expiré)
[CACHE STALE] home-ongoing | HOME | 0.52ms
[CACHE REVALIDATE] home-ongoing | HOME | 287.45ms

# Requête suivante (cache frais)
[CACHE HIT] home-ongoing | HOME | 0.43ms

Outils complémentaires

1. DevTools du navigateur

Network Tab

• Temps de réponse < 50ms = probablement du cache serveur
• Headers X-Cache si configurés
• Onglet "Timing" pour détails

Application → Cache Storage

Inspectez le cache du Service Worker :

• stripstream-cache-v1 : Ressources statiques
• stripstream-images-v1 : Images (covers + pages)

Actions disponibles :

• ✅ Voir le contenu de chaque cache
• 🔍 Chercher une URL spécifique
• 🗑️ Supprimer des entrées
• 🧹 Vider complètement un cache

Application → Service Workers

• État du Service Worker
• "Unregister" pour le désactiver
• "Update" pour forcer une mise à jour
• Console pour voir les logs SW

2. API de monitoring

Taille du cache

curl http://localhost:3000/api/komga/cache/size

Response :

{
  "sizeInBytes": 15728640,
  "itemCount": 234
}

Mode actuel

curl http://localhost:3000/api/komga/cache/mode

Response :

{
  "mode": "memory"
}

Vider le cache

curl -X POST http://localhost:3000/api/komga/cache/clear

Changer de mode

curl -X POST http://localhost:3000/api/komga/cache/mode \
  -H "Content-Type: application/json" \
  -d '{"mode": "file"}'

3. Mode fichier : Inspection du disque

Si vous utilisez le mode file, le cache est stocké sur disque :

# Voir la structure du cache
ls -la .cache/

# Voir la taille totale
du -sh .cache/

# Compter les fichiers
find .cache/ -type f | wc -l

# Voir le contenu d'une entrée
cat .cache/user-id/home-ongoing.json | jq

Exemple de contenu :

{
  "data": {
    "ongoing": [...],
    "recentlyRead": [...],
    "onDeck": [...]
  },
  "expiry": 1704067200000
}

Patterns de debug courants

Identifier un problème de cache

Symptôme : Les données ne se rafraîchissent pas

# 1. Vérifier si STALE + REVALIDATE se produisent
CACHE_DEBUG=true

# 2. Observer les logs
[CACHE STALE] series-123 | SERIES | 0.5ms
[CACHE REVALIDATE ERROR] series-123: Network error

# 3. Problème identifié : Komga inaccessible

Solution : Vérifier la connectivité avec Komga

Optimiser les performances

Objectif : Identifier les requêtes lentes

# Activer les logs
CACHE_DEBUG=true

# Observer les temps
[CACHE MISS] library-456-all-series | SERIES
[CACHE SET] library-456-all-series | SERIES | 2847.32ms  # ⚠️ Très lent !

Solution :

• Vérifier la taille des bibliothèques
• Augmenter le TTL pour ces données
• Considérer la pagination

Vérifier le mode de cache

# Logs après redémarrage
[CACHE MISS] home-ongoing | HOME  # Mode memory : normal
[CACHE HIT] home-ongoing | HOME   # Mode file : cache persisté

En mode memory : tous les caches sont vides au démarrage
En mode file : les caches survivent au redémarrage

Performance attendue

Temps de réponse normaux

Scénario	Temps attendu	Log
Cache HIT	< 1ms	[CACHE HIT] ... | 0.45ms
Cache STALE	< 1ms	[CACHE STALE] ... | 0.52ms
Cache MISS (petit)	50-200ms	[CACHE SET] ... | 124.18ms
Cache MISS (gros)	200-1000ms	[CACHE SET] ... | 847.32ms
Revalidate (background)	Variable	[CACHE REVALIDATE] ... | 287.45ms

Signaux d'alerte

⚠️ Cache HIT > 10ms

• Problème : Disque lent (mode file)
• Solution : Vérifier les I/O, passer en mode memory

⚠️ Cache MISS > 2000ms

• Problème : Komga très lent ou données énormes
• Solution : Vérifier Komga, optimiser la requête

⚠️ REVALIDATE ERROR fréquents

• Problème : Komga instable ou réseau
• Solution : Augmenter les timeouts, vérifier la connectivité

⚠️ Trop de MISS successifs

• Problème : Cache pas conservé ou TTL trop court
• Solution : Vérifier le mode, augmenter les TTL

Désactiver les logs

Pour désactiver les logs de cache en production :

# .env
CACHE_DEBUG=false

# ou simplement commenter/supprimer la ligne
# CACHE_DEBUG=true

Les logs sont automatiquement désactivés si la variable n'est pas définie.

Logs et performance

Impact sur les performances :

• Overhead : < 0.1ms par opération
• Pas d'écriture disque (juste console)
• Pas d'accumulation en mémoire
• Safe pour la production

Recommandations :

• ✅ Activé en développement
• ✅ Activé temporairement en production pour diagnostics
• ❌ Pas nécessaire en production normale

Conclusion

Le système de logs de cache est conçu pour être :

• 🎯 Simple : Format clair et concis
• ⚡ Rapide : Impact négligeable sur les performances
• 🔧 Utile : Informations essentielles pour le debug
• 🔒 Optionnel : Désactivé par défaut

Pour la plupart des besoins de debug, les DevTools du navigateur suffisent.
Les logs serveur sont utiles pour comprendre le comportement du cache côté backend.