Monitorización de Redis Metrics con ClickStack

Integración con una instalación existente de Redis

En esta sección se explica cómo configurar su instalación existente de Redis para enviar métricas a ClickStack mediante la configuración del ClickStack OTel collector con el Redis receiver.

Si desea probar la integración de Redis Metrics antes de configurar su propio entorno existente, puede hacerlo con nuestro demo dataset preconfigurado en la siguiente sección.

Requisitos previos

Instancia de ClickStack en funcionamiento
Instalación existente de Redis (versión 3.0 o posterior)
Acceso de red desde ClickStack a Redis (puerto predeterminado: 6379)
Contraseña de Redis si la autenticación está habilitada

Verifique la conexión con Redis

Primero, verifique que puede conectarse a Redis y que el comando INFO funcione:

# 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 requiere autenticación:

redis-cli -a <your-password> ping

Endpoints habituales de Redis:

Instalación local: localhost:6379
Docker: Usa el nombre del contenedor o del servicio (p. ej., redis:6379)
Remoto: <redis-host>:6379

Crear una configuración personalizada del OTel collector

ClickStack le permite ampliar la configuración base del OpenTelemetry Collector montando un archivo de configuración personalizado y definiendo una variable de entorno. La configuración personalizada se combina con la configuración base administrada por HyperDX mediante OpAMP.

Cree un archivo llamado redis-metrics.yaml con la siguiente configuración:

redis-metrics.yamlyaml

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

Esta configuración:

Se conecta a Redis en localhost:6379 (ajusta el endpoint según tu entorno)
Recopila métricas cada 10 segundos
Recopila métricas clave de rendimiento (comandos, clientes, memoria y estadísticas del espacio de claves)
Establece el atributo de recurso service.name requerido según las convenciones semánticas de OpenTelemetry
Envía las métricas al ClickHouse exporter a través de una canalización dedicada

Métricas clave recopiladas:

redis.commands.processed - Comandos procesados por segundo
redis.clients.connected - Número de clientes conectados
redis.clients.blocked - Clientes bloqueados en llamadas bloqueantes
redis.memory.used - Memoria utilizada por Redis en bytes
redis.memory.peak - Uso máximo de memoria
redis.keyspace.hits - Búsquedas de claves correctas
redis.keyspace.misses - Búsquedas de claves fallidas (para calcular la tasa de aciertos de caché)
redis.keys.expired - Claves expiradas
redis.keys.evicted - Claves desalojadas debido a la presión de memoria
redis.connections.received - Total de conexiones recibidas
redis.connections.rejected - Conexiones rechazadas

Configurar ClickStack para cargar una configuración personalizada

Para habilitar una configuración personalizada del collector en su implementación actual de ClickStack, debe:

Montar el archivo de configuración personalizada en /etc/otelcol-contrib/custom.config.yaml
Establecer la variable de entorno CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Asegurar la conectividad de red entre ClickStack y Redis

Opción 1: Docker Compose

Actualice la configuración de su implementación de 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

Opción 2: Docker run (imagen todo en uno)

Si usas la imagen todo en uno con 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

Importante: Si Redis se está ejecutando en otro contenedor, usa la red de 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

Verifica las métricas en HyperDX

Una vez configurado, inicia sesión en HyperDX y verifica que las métricas estén llegando:

Ve al explorador de métricas
Busca métricas que empiecen por redis. (p. ej., redis.commands.processed, redis.memory.used)
Deberías ver puntos de datos de métricas según el intervalo de recopilación configurado

Conjunto de datos de demostración

Para quienes quieran probar la integración de Redis Metrics antes de configurar sus sistemas de producción, proporcionamos un conjunto de datos pregenerado con patrones realistas de Redis Metrics.

Descargue el conjunto de datos de métricas de muestra

Descargue los archivos de métricas pregenerados (24 horas de Redis Metrics con patrones realistas):

# Descargar métricas gauge (memoria, ratio de fragmentación)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/redis/redis-metrics-gauge.csv

# Descargar métricas sum (comandos, conexiones, estadísticas de keyspace)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/redis/redis-metrics-sum.csv

El conjunto de datos incluye patrones realistas:

Evento de calentamiento de la caché (06:00) - La tasa de aciertos sube del 30 % al 80 %
Pico de tráfico (14:30-14:45) - Aumento del tráfico de 5 veces con presión sobre las conexiones
Presión de memoria (20:00) - Expulsión de claves y degradación del rendimiento de la caché
Patrones diarios de tráfico - Picos en horario laboral, descensos por la noche y micro-picos aleatorios

Inicie ClickStack

Inicie una instancia de ClickStack:

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

Espere aproximadamente 30 segundos a que ClickStack se inicie por completo.

Cargue las métricas en ClickStack

Cargue las métricas directamente en ClickHouse:

# Cargar métricas gauge (memoria, fragmentación)
cat redis-metrics-gauge.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

# Cargar métricas sum (comandos, conexiones, keyspace)
cat redis-metrics-sum.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"

Verifique las métricas en HyperDX

Una vez cargadas, la forma más rápida de ver sus métricas es a través del dashboard preconfigurado.

Vaya a la sección Dashboards y visualización para importar el dashboard y ver todas las Redis Metrics de una sola vez.

Dashboards y visualización

Para ayudarte a empezar a monitorizar Redis con ClickStack, proporcionamos visualizaciones esenciales para Redis Metrics.

Descargar la configuración del dashboard

Descargar el archivo de configuración del dashboard.

Importar el dashboard preconfigurado

Abre HyperDX y ve a la sección Dashboards
Haz clic en Import Dashboard en la esquina superior derecha, en el menú de puntos suspensivos

Sube el archivo redis-metrics-dashboard.json y haz clic en Finish Import

Ver el dashboard

El dashboard se creará con todas las visualizaciones ya configuradas:

Solución de problemas

La configuración personalizada no se carga

Verifica que la variable de entorno CUSTOM_OTELCOL_CONFIG_FILE esté configurada correctamente:

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Compruebe que el archivo de configuración personalizado esté montado en /etc/otelcol-contrib/custom.config.yaml:

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

Revise el contenido de la configuración personalizada para comprobar que se puede leer:

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

No aparecen métricas en HyperDX

Verifica que Redis sea accesible desde el collector:

# Desde el contenedor de ClickStack
docker exec <clickstack-container> redis-cli -h <redis-host> ping
# Salida esperada: PONG

Compruebe si funciona el comando INFO de Redis:

docker exec <clickstack-container> redis-cli -h <redis-host> INFO stats
# Debería mostrar estadísticas de Redis

Verifica que la configuración efectiva incluya tu Redis receiver:

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

Revisa si hay errores en los logs del collector:

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i redis
# Buscar errores de conexión o fallos de autenticación

Errores de autenticación

Si aparecen errores de autenticación en los logs:

# Verificar que Redis requiere autenticación
redis-cli CONFIG GET requirepass

# Probar autenticación
redis-cli -a <password> ping

# Asegurarse de que la contraseña esté configurada en el entorno de ClickStack
docker exec <clickstack-container> printenv REDIS_PASSWORD

Actualiza tu configuración para usar la contraseña:

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

Problemas de conectividad de red

Si ClickStack no puede conectarse a Redis:

# Comprobar si ambos contenedores están en la misma red
docker network inspect <network-name>

# Probar la conectividad
docker exec <clickstack-container> ping redis
docker exec <clickstack-container> telnet redis 6379

Asegúrate de que tu archivo de Docker Compose o tus comandos docker run sitúen ambos contenedores en la misma red.

Siguientes pasos

Configura alertas para métricas críticas (umbrales de uso de memoria, límites de conexión, caídas en la tasa de aciertos de la caché)
Crea dashboards adicionales para casos de uso específicos (retraso de replicación, rendimiento de la persistencia)
Supervisa varias instancias de Redis duplicando la configuración del receiver con distintos endpoints y nombres de servicio

Puesta en producción

Esta guía amplía el OpenTelemetry Collector integrado de ClickStack para facilitar una configuración rápida. Para implementaciones de producción, recomendamos ejecutar su propio OTel collector y enviar los datos al endpoint OTLP de ClickStack. Consulte Envío de datos de OpenTelemetry para la configuración de producción.