Erreurs courantes de Redis et leurs correctifs avec des exemples pratiques

Introduction

Les erreurs Redis surviennent généralement lors de pics de charge : un délai d'attente soudain, un avertissement de mémoire saturée ou une réplique qui cesse de se synchroniser. Ce guide couvre les erreurs Redis courantes et leurs correctifs avec des exemples pratiques, prêts à copier-coller. Il s'adresse aux développeurs, aux ingénieurs DevOps et aux équipes techniques de startups qui doivent passer d'un problème observé à un résultat vérifié sans deviner.

Vous apprendrez à inventorier votre version et votre topologie Redis, à modifier la configuration en toute sécurité, à utiliser les diagnostics intégrés, à récupérer après un échec et à éviter les erreurs opérationnelles les plus fréquentes. Chaque section comprend de vraies commandes, les résultats attendus, les signes d'échec et une étape de vérification. L'approche est opérationnelle : observer avant de changer, limiter le rayon d'impact, utiliser des espaces réservés plutôt que des secrets et documenter la récupération avant d'en avoir besoin.

Comment utiliser ce guide

Chaque procédure suit le même schéma pratique :

• Observer. Exécutez une commande en lecture seule pour capturer l'état actuel.
• Interpréter. Comparez la sortie avec le signal attendu.
• Changer (si nécessaire). Appliquez le plus petit changement de configuration justifié.
• Vérifier. Confirmez le nouvel état avec une autre commande en lecture seule.
• Récupérer. Connaissez le chemin exact de retour en arrière si la vérification échoue.

Tous les exemples supposent Redis 5.0 ou ultérieur, mais la plupart des commandes fonctionnent sur des versions antérieures. Lorsqu'une version compte, cela est indiqué explicitement.

Inventaire de la version et de l'environnement

Avant de toucher à quoi que ce soit, sachez exactement ce que vous exécutez. Une grande partie des impasses du dépannage Redis survient parce que l'opérateur identifie mal la version, la topologie ou le composant qui est réellement en panne. Les correctifs Redis échouent souvent parce qu'ils sont appliqués au mauvais processus ou au mauvais fichier de configuration.

Étape 1 : Identifier la version de Redis installée

Connectez-vous à l'instance Redis et exécutez :

redis-cli INFO server

Recherchez le champ redis_version :

redis_version:7.2.4

Si vous utilisez Docker, obtenez le tag de l'image :

docker inspect --format '{{.Config.Image}}' <nom-du-conteneur>

Exemple de sortie :

redis:7.2-alpine

Prérequis : redis-cli doit pouvoir se connecter. Si l'instance exige un mot de passe, utilisez redis-cli -a '<mot-de-passe>' INFO server ou définissez la variable d'environnement REDISCLI_AUTH. Ne collez jamais de véritables identifiants dans un document partagé ; utilisez un espace réservé comme <mot-de-passe>.

Étape 2 : Capturer la topologie de déploiement

Déterminez si vous exécutez en mode autonome, sentinelle ou cluster. Pour les instances autonomes et gérées par sentinelle, exécutez :

redis-cli INFO replication

Sortie attendue pour un primaire autonome :

role:master
connected_slaves:0

Pour une réplique :

role:slave
master_host:10.0.0.5
master_port:6379
master_link_status:up

Pour Redis Cluster, utilisez :

redis-cli CLUSTER INFO

La première ligne indique cluster_state:ok lorsqu'il est sain. Si elle indique cluster_state:fail, passez aux sections sur les modes de défaillance.

Étape 3 : Enregistrer des données d'observabilité en lecture seule

Capturez les horodatages et l'état actuel pour une comparaison ultérieure :

date -u +"%Y-%m-%dT%H:%M:%SZ"
redis-cli INFO stats | grep -E 'total_connections_received|total_commands_processed|instantaneous_ops_per_sec'
redis-cli CONFIG GET maxmemory maxmemory-policy

Exemple de sortie :

2025-03-21T10:32:15Z
total_connections_received:4231
total_commands_processed:8923401
instantaneous_ops_per_sec:540
maxmemory:0
maxmemory-policy:noeviction

Stockez cet instantané dans vos notes d'incident. C'est votre référence de base pour la vérification après changement.

Ce qui peut mal se passer

• Mauvais binaire Redis. Exécuter redis-cli depuis votre ordinateur portable contre un serveur peut entraîner une incompatibilité de version. Exécutez toujours redis-cli --version d'abord et comparez.
• Connexion à la mauvaise base de données. Par défaut, Redis utilise la base de données 0. Si votre application écrit dans la base de données 3, un KEYS * sur la base 0 ne montre rien. Utilisez SELECT 3 avant l'inspection.
• Authentification manquante. Si le serveur exige un mot de passe, redis-cli INFO renvoie NOAUTH Authentication required. Corrigez avec redis-cli -a '<mot-de-passe>' ou définissez requirepass temporairement uniquement dans un environnement de test.

Chemin de configuration sûr

Les changements de configuration sont l'une des principales causes d'incidents Redis. Le chemin sûr est le suivant : inspecter le paramètre actuel, tester le changement dans un environnement de préproduction, l'appliquer en production avec un plan de retour en arrière, puis vérifier le résultat. Ne modifiez jamais le fichier de configuration directement comme première action.

Lire la configuration actuelle

Toute la configuration d'exécution est disponible via CONFIG GET :

redis-cli CONFIG GET maxmemory
redis-cli CONFIG GET save
redis-cli CONFIG GET appendonly

Exemple de sortie :

maxmemory
0
save
3600 1 300 100 60 10000
appendonly
no

Les directives save signifient : sauvegarder après 3600 secondes si au moins 1 clé a changé, après 300 secondes si au moins 100 clés ont changé, après 60 secondes si au moins 10000 clés ont changé.

Faire un petit changement justifié

Supposons que votre surveillance montre que l'utilisation de la mémoire approche de la RAM physique du serveur. Vous voulez définir maxmemory à 4 Go et utiliser l'éviction allkeys-lru. D'abord, vérifiez le maxmemory actuel :

redis-cli CONFIG GET maxmemory

Sortie : maxmemory 0 (illimité).

Appliquez ensuite le changement à l'exécution :

redis-cli CONFIG SET maxmemory 4gb
redis-cli CONFIG SET maxmemory-policy allkeys-lru

Sortie attendue :

OK
OK

Vérifiez maintenant :

redis-cli CONFIG GET maxmemory maxmemory-policy

Sortie :

maxmemory
4294967296
maxmemory-policy
allkeys-lru

Rayon d'impact : Ce paramètre n'affecte que l'instance connectée. Dans une configuration sentinelle ou cluster, vous devez l'appliquer à chaque nœud. Dans un ensemble de répliques, appliquez-le d'abord au maître, puis à chaque réplique.

Retour en arrière : Si la politique d'éviction provoque une perte de clés inattendue, revenez immédiatement en arrière :

redis-cli CONFIG SET maxmemory 0
redis-cli CONFIG SET maxmemory-policy noeviction

Vérifiez à nouveau avec CONFIG GET.

Rendre le changement persistant

Les changements d'exécution sont perdus après un redémarrage. Pour les rendre permanents, mettez à jour le fichier de configuration Redis. Trouvez son chemin :

redis-cli CONFIG GET dir
redis-cli CONFIG GET config_file

Exemple de sortie :

dir
/var/lib/redis
config_file
/etc/redis/redis.conf

Utilisez sed ou votre éditeur pour modifier les valeurs. Par exemple :

sudo sed -i 's/^# maxmemory <bytes>/maxmemory 4gb/' /etc/redis/redis.conf
sudo sed -i 's/^# maxmemory-policy noeviction/maxmemory-policy allkeys-lru/' /etc/redis/redis.conf

Redémarrez ensuite Redis en toute sécurité. Testez d'abord la configuration :

redis-server /etc/redis/redis.conf --test-memory 4096mb

Si le test réussit, redémarrez le service :

sudo systemctl restart redis-server

Vérifiez que le paramètre a survécu :

redis-cli CONFIG GET maxmemory maxmemory-policy

N'utilisez jamais de véritables identifiants dans les exemples de configuration. Si vous définissez requirepass, utilisez un espace réservé comme votre-mot-de-passe-fort et faites-le tourner régulièrement.

Vérification et diagnostics

Le diagnostic des problèmes Redis exige de séparer les symptômes des causes profondes. Utilisez judicieusement les commandes intégrées INFO, SLOWLOG, LATENCY et MONITOR. Chaque commande a un coût, alors ne les exécutez que lorsque cela est nécessaire.

Vérifier la santé globale avec INFO

La commande INFO renvoie des dizaines de métriques. Concentrez-vous sur les sections pertinentes pour votre problème :

redis-cli INFO

Champs clés à surveiller :

• connected_clients : Nombre de connexions actuelles. Un pic soudain peut indiquer une fuite de connexions dans votre application.
• used_memory_human : Utilisation actuelle de la mémoire.
• maxmemory_human : Limite configurée.
• total_net_input_bytes / total_net_output_bytes : Débit réseau.
• keyspace_hits / keyspace_misses : Efficacité du cache. Un faible taux de réussite suggère une mauvaise conception des clés.
• rejected_connections : Nombre de connexions rejetées en raison de maxclients. Si non nul, augmentez maxclients ou corrigez la fuite côté client.

Exemple de sortie partielle :

# Memory
used_memory:1024000
used_memory_human:1.00M
maxmemory:4294967296
maxmemory_human:4.00G
# Stats
total_connections_received:5021
total_commands_processed:10234987
rejected_connections:0
keyspace_hits:982341
keyspace_misses:10234

Identifier les commandes lentes avec SLOWLOG

Les commandes lentes dégradent les performances. Vérifiez le slowlog :

redis-cli SLOWLOG GET 10

Exemple de sortie :

1) 1) (integer) 3
   2) (integer) 1711026000
   3) (integer) 1520
   4) 1) "KEYS"
      2) "customer:*"
   5) "127.0.0.1:54321"
   6) ""

Cela montre qu'une commande KEYS customer:* a pris 1520 microsecondes. En production, KEYS peut bloquer Redis pendant des secondes s'il y a beaucoup de clés. Remplacez-la par SCAN.

Configurez le seuil du slowlog pour capturer les commandes plus lentes :

redis-cli CONFIG SET slowlog-log-slower-than 10000

Cela enregistre les commandes plus lentes que 10 millisecondes.

Diagnostiquer les pics de latence avec LATENCY

Redis fournit un moniteur de latence. Activez-le avec un seuil :

redis-cli CONFIG SET latency-monitor-threshold 100

Puis, après une certaine activité, vérifiez les événements de latence :

redis-cli LATENCY LATEST

Exemple de sortie :

1) 1) "command"
   2) (integer) 1711026000
   3) (integer) 250
   4) (integer) 100

Cela montre qu'une commande a pris 250 ms, dépassant le seuil de 100 ms. Utilisez LATENCY HISTORY command pour une série temporelle.

Attention : MONITOR diffuse chaque commande, ce qui peut affecter les performances. Utilisez-le uniquement pour de courtes sessions de débogage, jamais en production sous charge.

Inspecter les connexions client

Une erreur courante est un délai d'attente client mal configuré. Voyez les clients actifs :

redis-cli CLIENT LIST

Exemple de ligne :

id=123 addr=10.0.0.8:56789 fd=8 name=app-server age=3600 idle=320 flags=N db=0 sub=0 psub=0 multi=-1 qbuf=0 qbuf-free=0 obl=0 oll=0 omem=0 events=r cmd=get

age est le temps de connexion total, idle est le temps depuis la dernière commande. De nombreuses connexions avec un idle élevé peuvent indiquer un client qui ne ferme pas correctement ses connexions.

Modes de défaillance et récupération

Les défaillances Redis se regroupent en quelques modèles : épuisement de la mémoire, erreurs de persistance, rupture de la réplication et problèmes de réseau/connexion. Chaque section donne l'erreur, le diagnostic, le correctif et le retour en arrière.

1. Erreurs OOM (Out of Memory)

Message d'erreur :

OOM command not allowed when used memory > 'maxmemory'

Cela signifie que Redis a atteint la limite maxmemory et que la politique d'éviction ne peut pas libérer de mémoire (généralement noeviction).

Diagnostic :

redis-cli INFO memory

Comparez used_memory_human avec maxmemory_human. S'ils sont égaux ou proches, vous êtes à la limite.

Correctif (choisissez-en un) :

1. Évacuer les clés moins importantes en définissant une politique d'éviction :

   redis-cli CONFIG SET maxmemory-policy allkeys-lru

1. Augmenter maxmemory si le serveur a de la RAM disponible :

   redis-cli CONFIG SET maxmemory 8gb

1. Supprimer manuellement les clés inutilisées : utilisez SCAN et DEL pour des motifs spécifiques.

Vérification :

redis-cli INFO memory | grep used_memory_human
redis-cli CONFIG GET maxmemory-policy

Retour en arrière : Si l'éviction provoque une perte de données que vous ne pouvez pas accepter, remettez la politique à noeviction et augmentez la mémoire.

2. Erreurs de persistance

Redis persiste les données via des instantanés RDB et/ou des journaux AOF. Les échecs peuvent entraîner une perte de données.

Exemples de messages d'erreur :

MISCONF Redis is configured to save RDB snapshots, but it is currently unable to persist on disk

Diagnostic :

redis-cli INFO persistence

Recherchez rdb_last_bgsave_status:err ou aof_last_write_status:err. Vérifiez l'espace disque :

df -h /var/lib/redis

Correctif :

• Si le disque est plein, libérez de l'espace ou changez le dir vers un volume plus grand.
• Vérifiez les permissions sur le dir et le dbfilename :

  ls -ld /var/lib/redis

L'utilisateur Redis doit avoir la permission d'écrire.

• Si la sauvegarde RDB échoue fréquemment, ajustez les intervalles save ou désactivez temporairement RDB (non recommandé en production).
• Pour les erreurs AOF, vérifiez la corruption du fichier AOF et envisagez redis-check-aof --fix.

Vérification :

redis-cli INFO persistence | grep rdb_last_bgsave_status

Attendu : rdb_last_bgsave_status:ok.

3. Problèmes de réplication

Message d'erreur :

MASTER down

ou le master_link_status de la réplique est down.

Diagnostic :

Sur la réplique :

redis-cli INFO replication

Vérifiez master_link_status. Si down, examinez master_host, master_port et la connectivité :

redis-cli -h <hôte-maître> -p 6379 PING

Correctif :

• Assurez la connectivité réseau (pare-feu, groupes de sécurité).
• Corrigez la configuration de la réplique : replicaof <hôte-maître> <port-maître>.
• Si l'authentification est activée, définissez masterauth sur la réplique.
• Si la réplique a été promue manuellement, rétrogradez-la ou réinitialisez la topologie.

Vérification :

redis-cli INFO replication | grep master_link_status

Attendu : master_link_status:up.

4. Délais d'attente et refus de connexion

Message d'erreur :

Could not connect to Redis at 127.0.0.1:6379: Connection refused

Cela signifie que le serveur Redis ne fonctionne pas ou n'écoute pas sur cette adresse.

Diagnostic :

redis-cli PING

Si refusé, vérifiez le service :

sudo systemctl status redis-server

S'il fonctionne, vérifiez bind et port :

redis-cli CONFIG GET bind port

Correctif :

• Démarrez le service : sudo systemctl start redis-server.
• Si l'adresse de liaison est incorrecte, ajustez-la dans le fichier de configuration et redémarrez.
• Si vous utilisez Docker, assurez-vous que le mappage de port est correct : -p 6379:6379.

Vérification :

redis-cli PING

Attendu : PONG.

5. Erreurs client : MAXCLIENTS atteint

Message d'erreur :

ERR max number of clients reached

Diagnostic :

redis-cli INFO clients

Comparez connected_clients à maxclients.

Correctif :

• Augmentez maxclients :

  redis-cli CONFIG SET maxclients 20000

• Trouvez et corrigez les fuites de connexions client dans votre application. Utilisez CLIENT LIST pour identifier les coupables.

Vérification :

redis-cli CONFIG GET maxclients

Liste de contrôle des opérations

Utilisez cette liste de contrôle avant et après tout changement Redis. Attribuez chaque élément à un seul responsable et révisez la liste lors de chaque revue d'incident.

Chaque responsable doit rendre compte de son élément et du résultat lors de la réunion opérationnelle hebdomadaire.

Pièges et erreurs courants

Les erreurs suivantes reviennent dans les déploiements Redis. Comprenez pourquoi elles se produisent et comment les éviter.

1. Utiliser KEYS en production

Pourquoi cela arrive : Les développeurs testent avec de petits ensembles de données et KEYS est pratique. En production, cela bloque le serveur Redis monothread pour chaque clé correspondante, provoquant des pics de latence.

Comment l'éviter : Utilisez SCAN avec un curseur pour une itération non bloquante, par exemple redis-cli --scan --pattern 'customer:*'. Si vous devez absolument supprimer des clés correspondantes, utilisez UNLINK au lieu de DEL pour éviter le blocage.

2. Ignorer les paramètres de persistance

Pourquoi cela arrive : Les développeurs s'appuient sur les paramètres par défaut et supposent que les données survivront à un redémarrage. Mais les intervalles save par défaut peuvent provoquer une perte de données si le processus plante entre deux instantanés.

Comment l'éviter : Configurez un compromis entre performance et durabilité. Pour une perte de données minimale, utilisez le fichier append-only (AOF) avec appendfsync everysec. Pour les données critiques, envisagez appendfsync always (avec un coût en performance). Testez régulièrement votre récupération à partir de RDB et AOF.

3. Définir maxmemory à 0

Pourquoi cela arrive : La valeur par défaut maxmemory 0 signifie aucune limite, ce qui est bien pour le développement mais dangereux en production. Lorsque Redis utilise toute la mémoire, le tueur OOM du système d'exploitation peut mettre fin à Redis ou à d'autres processus.

Comment l'éviter : Définissez toujours maxmemory à une valeur inférieure à la RAM physique du serveur, en laissant de la place pour l'OS. Surveillez le ratio used_memory sur maxmemory.

4. Exécuter Redis sans authentification sur une interface publique

Pourquoi cela arrive : La configuration par défaut se lie à toutes les interfaces et n'a pas de mot de passe. La sécurité est une réflexion après coup dans les tests internes, mais de nombreuses instances sont accidentellement exposées à Internet, entraînant un vol de données ou un ransomware.

Comment l'éviter : Liez-vous à une interface privée (bind 10.0.0.5), définissez requirepass avec un mot de passe fort et utilisez des règles de pare-feu ou des groupes de sécurité pour restreindre l'accès. Préférez TLS pour le chiffrement réseau.

5. Mal configurer la réplication

Pourquoi cela arrive : Copier un fichier de configuration du maître vers une réplique sans changer replicaof entraîne deux maîtres indépendants ou une boucle de réplication.

Comment l'éviter : Vérifiez toujours INFO replication sur les deux nœuds. Sur la réplique, assurez-vous que replicaof <ip-maître> <port-maître> est défini et que masterauth correspond au requirepass du maître. Utilisez redis-cli SLAVEOF NO ONE uniquement lorsque vous promouvez une réplique intentionnellement.

6. Négliger la surveillance du slowlog et de la latence

Pourquoi cela arrive : Les équipes se concentrent sur les erreurs fonctionnelles et ignorent les performances jusqu'à ce que les utilisateurs se plaignent. Les commandes lentes peuvent ne pas échouer mais dégrader toute l'application.

Comment l'éviter : Activez le slowlog (par exemple, slowlog-log-slower-than 10000) et le moniteur de latence (latency-monitor-threshold 100). Révisez-les régulièrement et après tout déploiement de code.

Conclusion

Les erreurs courantes de Redis ne sont généralement pas mystérieuses. Elles découlent d'une mauvaise configuration, d'un épuisement des ressources ou d'un comportement client incorrect. Les correctifs de ce guide sont pratiques et adaptés à la version, mais ils ne fonctionnent que si vous observez avant de changer et vérifiez après avoir changé.

Commencez par l'inventaire de la version et de l'environnement pour connaître votre référence de base. N'apportez que le plus petit changement justifié en utilisant le chemin de configuration sûr. Utilisez les commandes de vérification et de diagnostic pour confirmer le correctif. Pour chaque mode de défaillance de cet article, pratiquez les étapes de récupération dans un environnement de préproduction avant d'en avoir besoin en production.

Enfin, adoptez la liste de contrôle des opérations et attribuez un seul responsable à chaque élément. Redis fonctionne bien lorsqu'il est exploité avec discipline. Choisissez dès aujourd'hui une vérification à faible risque de ce guide, exécutez la commande documentée et comparez le résultat avec la sortie attendue. Si la sortie correspond, vous venez d'améliorer la fiabilité de votre déploiement Redis.

Révisez votre configuration Redis mensuellement : revisitez maxmemory, maxclients, les paramètres de persistance et la santé de la réplication. Un Redis fiable n'est pas un accident ; c'est le résultat d'opérations cohérentes et observables.