Surveiller les métriques Redis avec ClickStack

En brefSurveillez les métriques de performance de Redis dans ClickStack à l’aide du récepteur Redis OTel. Comprend un jeu de données de démonstration et un tableau de bord préconfiguré.

Intégration avec une instance Redis existante

Cette section explique comment configurer votre installation Redis existante pour envoyer des métriques à ClickStack en configurant le ClickStack OTel collector avec le Redis récepteur. Si vous souhaitez tester l’intégration Redis Metrics avant de configurer votre propre environnement, vous pouvez utiliser notre jeu de données de démonstration préconfiguré dans la section suivante.

Prérequis

Instance ClickStack en fonctionnement
Installation Redis existante (version 3.0 ou ultérieure)
Accès réseau de ClickStack à Redis (port par défaut 6379)
Mot de passe Redis si l’authentification est activée

Vérifiez la connexion à Redis

Commencez par vérifier que vous pouvez vous connecter à Redis et que la commande INFO fonctionne :

# Test connection
redis-cli ping
# Expected output: PONG

# Test INFO command (used by metrics collector)
redis-cli INFO server
# Should display Redis server information

Si Redis nécessite une authentification :

redis-cli -a <your-password> ping

Endpoints Redis courants :

Installation locale : localhost:6379
Docker : utilisez le nom du conteneur ou le nom du service (par ex. redis:6379)
À distance : <redis-host>:6379

Créer une configuration personnalisée pour l’OTel collector

ClickStack vous permet d’étendre la configuration de base de l’OpenTelemetry Collector en montant un fichier de configuration personnalisé et en définissant une variable d’environnement. Cette configuration personnalisée est fusionnée avec la configuration de base gérée par HyperDX via OpAMP.Créez un fichier nommé redis-metrics.yaml avec la configuration suivante :

redis-metrics.yaml

receivers:
  redis:
    endpoint: "localhost:6379"
    collection_interval: 10s
    # Uncomment if Redis requires authentication
    # password: ${env:REDIS_PASSWORD}
    
    # Configure which metrics to collect
    metrics:
      redis.commands.processed:
        enabled: true
      redis.clients.connected:
        enabled: true
      redis.memory.used:
        enabled: true
      redis.keyspace.hits:
        enabled: true
      redis.keyspace.misses:
        enabled: true
      redis.keys.evicted:
        enabled: true
      redis.keys.expired:
        enabled: true

processors:
  resource:
    attributes:
      - key: service.name
        value: "redis"
        action: upsert

service:
  pipelines:
    metrics/redis:
      receivers: [redis]
      processors:
        - resource
        - memory_limiter
        - batch
      exporters:
        - clickhouse

Cette configuration :

Se connecte à Redis sur localhost:6379 (ajustez le point de terminaison à votre configuration)
Collecte des métriques toutes les 10 secondes
Collecte les principales métriques de performance (commandes, clients, mémoire, statistiques de l’espace de clés)
Définit l’attribut de ressource service.name requis conformément aux conventions sémantiques OpenTelemetry
Achemine les métriques vers l’exporter ClickHouse via un pipeline dédié

Métriques clés collectées :

redis.commands.processed - Commandes traitées par seconde
redis.clients.connected - Nombre de clients connectés
redis.clients.blocked - Clients bloqués sur des appels bloquants
redis.memory.used - Mémoire utilisée par Redis en octets
redis.memory.peak - Pic d’utilisation de la mémoire
redis.keyspace.hits - Recherches de clés réussies
redis.keyspace.misses - Recherches de clés échouées (pour calculer le taux de réussite du cache)
redis.keys.expired - Clés expirées
redis.keys.evicted - Clés évincées en raison d’une pression mémoire
redis.connections.received - Nombre total de connexions reçues
redis.connections.rejected - Connexions rejetées

Vous ne définissez de nouveaux receivers, processors et pipelines que dans la config personnalisée
Les processors memory_limiter et batch, ainsi que l’exporter clickhouse, sont déjà définis dans la configuration de base de ClickStack ; vous n’avez qu’à les référencer par leur nom
Le processor resource définit l’attribut service.name requis conformément aux conventions sémantiques OpenTelemetry
En production avec authentification, stockez le mot de passe dans une variable d’environnement : ${env:REDIS_PASSWORD}
Ajustez collection_interval selon vos besoins (10s par défaut ; des valeurs plus faibles augmentent le volume de données)
Pour plusieurs instances Redis, personnalisez service.name pour les distinguer (par exemple, "redis-cache", "redis-sessions")

Configurer ClickStack pour charger une configuration personnalisée

Pour activer une configuration personnalisée du collecteur dans votre déploiement ClickStack existant, vous devez :

Monter le fichier de configuration personnalisé à l’emplacement /etc/otelcol-contrib/custom.config.yaml
Définir la variable d’environnement CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Vérifier la connectivité réseau entre ClickStack et Redis

Option 1 : Docker Compose

Mettez à jour la configuration de votre déploiement ClickStack :

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # Optional: If Redis requires authentication
      # - REDIS_PASSWORD=your-redis-password
      # ... other environment variables ...
    volumes:
      - ./redis-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      # ... other volumes ...
    # If Redis is in the same compose file:
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    # Optional: Enable authentication
    # command: redis-server --requirepass your-redis-password

Option 2 : Docker run (image tout-en-un)

Si vous utilisez l’image tout-en-un avec docker run :

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/redis-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  clickhouse/clickstack-all-in-one:latest

Important : Si Redis s’exécute dans un autre conteneur, utilisez le réseau Docker :

# Create a network
docker network create monitoring

# Run Redis on the network
docker run -d --name redis --network monitoring redis:7-alpine

# Run ClickStack on the same network (update endpoint to "redis:6379" in config)
docker run --name clickstack \
  --network monitoring \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/redis-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  clickhouse/clickstack-all-in-one:latest

Vérifier les métriques dans HyperDX

Une fois la configuration terminée, connectez-vous à HyperDX et vérifiez que les métriques sont bien collectées :

Accédez à Metrics Explorer
Recherchez les métriques commençant par redis. (par ex., redis.commands.processed, redis.memory.used)
Vous devriez voir apparaître des points de données selon l’intervalle de collecte configuré

Jeu de données de démonstration

Pour les utilisateurs qui souhaitent tester l’intégration Redis Metrics avant de configurer leurs systèmes de production, nous fournissons un jeu de données pré-généré contenant des profils Redis Metrics réalistes.

Télécharger l’exemple de jeu de données de métriques

Téléchargez les fichiers de métriques pré-générés (24 heures de Redis Metrics avec des profils réalistes) :

# Télécharger les métriques gauge (mémoire, ratio de fragmentation)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/redis/redis-metrics-gauge.csv

# Télécharger les métriques sum (commandes, connexions, statistiques keyspace)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/redis/redis-metrics-sum.csv

Le jeu de données inclut des profils réalistes :

Échauffement du cache (06:00) - Le taux de réussite passe de 30 % à 80 %
Pic de trafic (14:30-14:45) - Multiplication par 5 du trafic avec pression sur les connexions
Pression mémoire (20:00) - Évictions de clés et dégradation des performances du cache
Profils de trafic quotidiens - Pics pendant les heures ouvrées, baisse en soirée, micro-pics aléatoires

Démarrer ClickStack

Démarrez une instance ClickStack :

docker run -d --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest

Attendez environ 30 secondes pour que ClickStack démarre complètement.

Charger les métriques dans ClickStack

Chargez les métriques directement dans ClickHouse :

# Charger les métriques gauge (mémoire, fragmentation)
cat redis-metrics-gauge.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

# Charger les métriques sum (commandes, connexions, keyspace)
cat redis-metrics-sum.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"

Vérifier les métriques dans HyperDX

Une fois les données chargées, le moyen le plus rapide de visualiser vos métriques est d’utiliser le tableau de bord préconfiguré.Rendez-vous dans la section Dashboards and visualization pour importer le tableau de bord et afficher toutes les métriques Redis Metrics en une seule vue.

L’intervalle de temps du jeu de données de démonstration va de 2025-10-20 00:00:00 à 2025-10-21 05:00:00. Assurez-vous que l’intervalle de temps sélectionné dans HyperDX correspond à cette plage.Recherchez les profils intéressants suivants :

06:00 - Échauffement du cache (progression d’un faible taux de réussite)
14:30-14:45 - Pic de trafic (nombre élevé de connexions client, quelques rejets)
20:00 - Pression mémoire (début des évictions de clés)

Tableaux de bord et visualisations

Pour vous aider à démarrer la supervision de Redis avec ClickStack, nous fournissons les visualisations essentielles pour Redis Metrics.

la configuration du tableau de bord

Importer le tableau de bord préconfiguré

Ouvrez HyperDX et accédez à la section Dashboards
Cliquez sur Import Dashboard en haut à droite, dans le menu à points de suspension

Téléversez le fichier redis-metrics-dashboard.json, puis cliquez sur Finish Import

Afficher le tableau de bord

Le tableau de bord sera créé avec toutes les visualisations préconfigurées :

Pour le jeu de données de démonstration, définissez l’intervalle de temps sur 2025-10-20 05:00:00 - 2025-10-21 05:00:00 (UTC) (à ajuster selon votre fuseau horaire local). Par défaut, aucun intervalle de temps n’est défini pour le tableau de bord importé.

Dépannage

La config personnalisée ne se charge pas

Vérifiez que la variable d’environnement CUSTOM_OTELCOL_CONFIG_FILE est correctement définie :

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Vérifiez que le fichier de configuration personnalisé est monté dans /etc/otelcol-contrib/custom.config.yaml :

docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml

Consultez le contenu de la config personnalisée pour vérifier qu’il est bien lisible :

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml

Aucune métrique n’apparaît dans HyperDX

Vérifiez que Redis est accessible depuis le collector :

# From the ClickStack container
docker exec <clickstack-container> redis-cli -h <redis-host> ping
# Expected output: PONG

Vérifiez si la commande INFO de Redis fonctionne :

docker exec <clickstack-container> redis-cli -h <redis-host> INFO stats
# Should display Redis statistics

Vérifiez que la configuration effective inclut votre Redis récepteur :

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 "redis:"

Recherchez des erreurs dans les logs du collector :

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i redis
# Look for connection errors or authentication failures

Erreurs d’authentification

Si vous voyez des erreurs d’authentification dans les logs :

# Verify Redis requires authentication
redis-cli CONFIG GET requirepass

# Test authentication
redis-cli -a <password> ping

# Ensure password is set in ClickStack environment
docker exec <clickstack-container> printenv REDIS_PASSWORD

Mettez à jour votre configuration pour utiliser le mot de passe :

receivers:
  redis:
    endpoint: "redis:6379"
    password: ${env:REDIS_PASSWORD}

Problèmes de connectivité réseau

Si ClickStack ne peut pas atteindre Redis :

# Check if both containers are on the same network
docker network inspect <network-name>

# Test connectivity
docker exec <clickstack-container> ping redis
docker exec <clickstack-container> telnet redis 6379

Assurez-vous que votre fichier Docker Compose ou vos commandes docker run placent les deux conteneurs sur le même réseau.

Prochaines étapes

Configurez des alertes pour les métriques critiques (seuils d’utilisation de la mémoire, limites de connexion, baisse du taux de succès du cache)
Créez des tableaux de bord supplémentaires pour des cas d’usage spécifiques (retard de réplication, performances de persistance)
Surveillez plusieurs instances Redis en dupliquant la configuration du récepteur avec différents endpoints et noms de service

Passage en production

Ce guide s’appuie sur l’OpenTelemetry Collector intégré à ClickStack pour une mise en place rapide. Pour les déploiements en production, nous vous recommandons d’exécuter votre propre OTel Collector et d’envoyer les données vers l’endpoint OTLP de ClickStack. Consultez Envoyer des données OpenTelemetry pour la configuration de production.

​Intégration avec une instance Redis existante

Prérequis

​Vérifiez la connexion à Redis

​Créer une configuration personnalisée pour l’OTel collector

​Configurer ClickStack pour charger une configuration personnalisée

Option 1 : Docker Compose

Option 2 : Docker run (image tout-en-un)

​Vérifier les métriques dans HyperDX

​Jeu de données de démonstration

​Télécharger l’exemple de jeu de données de métriques

​Démarrer ClickStack

​Charger les métriques dans ClickStack

​Vérifier les métriques dans HyperDX

​Tableaux de bord et visualisations

​ la configuration du tableau de bord

​Importer le tableau de bord préconfiguré

​Afficher le tableau de bord

​Dépannage

​La config personnalisée ne se charge pas

​Aucune métrique n’apparaît dans HyperDX

​Erreurs d’authentification

​Problèmes de connectivité réseau

​Prochaines étapes

​Passage en production

Intégration avec une instance Redis existante

Vérifiez la connexion à Redis

Créer une configuration personnalisée pour l’OTel collector

Configurer ClickStack pour charger une configuration personnalisée

Vérifier les métriques dans HyperDX

Jeu de données de démonstration

Télécharger l’exemple de jeu de données de métriques

Démarrer ClickStack

Charger les métriques dans ClickStack

Vérifier les métriques dans HyperDX

Tableaux de bord et visualisations

la configuration du tableau de bord

Importer le tableau de bord préconfiguré

Afficher le tableau de bord

Dépannage

La config personnalisée ne se charge pas

Aucune métrique n’apparaît dans HyperDX

Erreurs d’authentification

Problèmes de connectivité réseau

Prochaines étapes

Passage en production