Monitoramento de métricas do Redis com o ClickStack

Integração com uma instalação existente do Redis

Esta seção explica como configurar sua instalação existente do Redis para enviar métricas ao ClickStack, configurando o ClickStack OTel collector com o Redis receiver.

Se quiser testar a integração métricas do Redis antes de configurar seu próprio ambiente, você pode usar nosso demo dataset pré-configurado na seção a seguir.

Pré-requisitos

Instância do ClickStack em execução
Instalação existente do Redis (versão 3.0 ou posterior)
Acesso de rede do ClickStack ao Redis (porta padrão 6379)
Senha do Redis, caso a autenticação esteja habilitada

Verifique a conexão com o Redis

Primeiro, verifique se consegue se conectar ao Redis e se o comando INFO funciona:

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

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

Se o Redis exigir autenticação:

redis-cli -a <your-password> ping

Endpoints comuns do Redis:

Instalação local: localhost:6379
Docker: use o nome do contêiner ou do serviço (por exemplo, redis:6379)
Remoto: <redis-host>:6379

Criar configuração personalizada do OTel collector

O ClickStack permite estender a configuração básica do OpenTelemetry collector ao montar um arquivo de configuração personalizado e definir uma variável de ambiente. A configuração personalizada é mesclada à configuração básica gerenciada pelo HyperDX via OpAMP.

Crie um arquivo chamado redis-metrics.yaml com a seguinte configuração:

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 configuração:

Conecta ao Redis em localhost:6379 (ajuste o endpoint para o seu ambiente)
Coleta métricas a cada 10 segundos
Coleta as principais métricas de desempenho (comandos, clientes, memória, estatísticas do keyspace)
Define o atributo de resource service.name obrigatório de acordo com as convenções semânticas do OpenTelemetry
Encaminha métricas para o ClickHouse exporter por meio de um pipeline dedicado

Principais métricas coletadas:

redis.commands.processed - Comandos processados por segundo
redis.clients.connected - Número de clientes conectados
redis.clients.blocked - Clientes bloqueados em chamadas bloqueantes
redis.memory.used - Memória usada pelo Redis em bytes
redis.memory.peak - Pico de uso de memória
redis.keyspace.hits - Buscas de chave bem-sucedidas
redis.keyspace.misses - Buscas de chave malsucedidas (para cálculo da taxa de acerto do cache)
redis.keys.expired - Chaves expiradas
redis.keys.evicted - Chaves removidas devido à pressão de memória
redis.connections.received - Total de conexões recebidas
redis.connections.rejected - Conexões rejeitadas

Configure o ClickStack para carregar uma configuração personalizada

Para habilitar uma configuração personalizada do coletor na implantação existente do ClickStack, você deve:

Montar o arquivo de configuração personalizado em /etc/otelcol-contrib/custom.config.yaml
Definir a variável de ambiente CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Garantir a conectividade de rede entre o ClickStack e o Redis

Opção 1: Docker Compose

Atualize a configuração de implantação do seu 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

Opção 2: `docker run` (imagem all-in-one)

Se estiver usando a imagem all-in-one com 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: Se o Redis estiver em execução em outro contêiner, use a rede do 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

Verifique as métricas no HyperDX

Depois de configurar, entre no HyperDX e verifique se as métricas estão sendo coletadas:

Acesse o explorador de métricas
Procure métricas que comecem com redis. (por exemplo, redis.commands.processed, redis.memory.used)
Você deverá ver pontos de dados das métricas aparecendo no intervalo de coleta configurado

Dataset de demonstração

Para usuários que desejam testar a integração métricas do Redis antes de configurar seus sistemas de produção, fornecemos um dataset pré-gerado com padrões realistas de métricas do Redis.

Baixe o dataset de métricas de exemplo

Baixe os arquivos de métricas pré-gerados (24 horas de métricas do Redis com padrões realistas):

# Baixar métricas gauge (memória, taxa de fragmentação)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/redis/redis-metrics-gauge.csv

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

O dataset inclui padrões realistas:

Evento de aquecimento de cache (06:00) - A taxa de acerto sobe de 30% para 80%
Pico de tráfego (14:30-14:45) - Pico de 5x no tráfego com pressão nas conexões
Pressão de memória (20:00) - Evicções de chaves e degradação do desempenho do cache
Padrões diários de tráfego - Picos no horário comercial, quedas à noite e micropicos aleatórios

Inicie o ClickStack

Inicie uma instância do ClickStack:

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

Aguarde cerca de 30 segundos para o ClickStack iniciar completamente.

Carregue métricas no ClickStack

Carregue as métricas diretamente no ClickHouse:

# Carregar métricas gauge (memória, fragmentação)
cat redis-metrics-gauge.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

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

Verifique as métricas no HyperDX

Depois de carregadas, a forma mais rápida de ver suas métricas é pelo dashboard pré-configurado.

Siga para a seção Painéis e visualização para importar o dashboard e ver todas as métricas do Redis de uma só vez.

Painéis e visualização

Para ajudar você a começar a monitorar o Redis com o ClickStack, fornecemos visualizações essenciais para métricas do Redis.

Baixar a configuração do dashboard

Baixe o arquivo de configuração do dashboard.

Importar o dashboard pré-configurado

Abra o HyperDX e navegue até a seção Painéis
Clique em Import Dashboard no canto superior direito, no menu de reticências

Faça upload do arquivo redis-metrics-dashboard.json e clique em Finish Import

Caixa de diálogo para concluir a importação

Visualize o dashboard

O dashboard será criado com todas as visualizações pré-configuradas:

Solução de problemas

Configuração personalizada não está carregando

Verifique se a variável de ambiente CUSTOM_OTELCOL_CONFIG_FILE está definida corretamente:

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Verifique se o arquivo de configuração personalizado está montado em /etc/otelcol-contrib/custom.config.yaml:

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

Veja o conteúdo da config personalizada para verificar se está legível:

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

As métricas não aparecem no HyperDX

Verifique se o Redis está acessível a partir do coletor:

# Do contêiner do ClickStack
docker exec <clickstack-container> redis-cli -h <redis-host> ping
# Saída esperada: PONG

Verifique se o comando INFO do Redis está funcionando:

docker exec <clickstack-container> redis-cli -h <redis-host> INFO stats
# Deve exibir estatísticas do Redis

Verifique se a configuração efetiva inclui o receiver do Redis:

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

Verifique se há erros nos logs do collector:

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i redis
# Procure erros de conexão ou falhas de autenticação

Erros de autenticação

Se você encontrar erros de autenticação nos logs:

# Verificar se o Redis requer autenticação
redis-cli CONFIG GET requirepass

# Testar autenticação
redis-cli -a <password> ping

# Verificar se a senha está definida no ambiente do ClickStack
docker exec <clickstack-container> printenv REDIS_PASSWORD

Atualize sua configuração para usar a senha:

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

Problemas de conectividade de rede

Se o ClickStack não conseguir se conectar ao Redis:

# Verifique se ambos os contêineres estão na mesma rede
docker network inspect <network-name>

# Teste a conectividade
docker exec <clickstack-container> ping redis
docker exec <clickstack-container> telnet redis 6379

Certifique-se de que o arquivo do Docker Compose ou os comandos docker run coloquem ambos os contêineres na mesma rede.

Próximos passos

Configure alertas para métricas críticas (limites de uso de memória, limites de conexão, quedas na taxa de acerto do cache)
Crie dashboards adicionais para casos de uso específicos (defasagem de replicação, desempenho da persistência)
Monitore várias instâncias do Redis duplicando a configuração do receiver com endpoints e nomes de serviço diferentes

Colocando em produção

Este guia usa o OpenTelemetry Collector integrado do ClickStack para uma configuração rápida. Para implantações em produção, recomendamos executar seu próprio OTel collector e enviar os dados para o endpoint OTLP do ClickStack. Consulte Enviando dados do OpenTelemetry para a configuração de produção.