Monitoramento de métricas do Redis com o ClickStack

Resumo rápidoMonitore as métricas de desempenho do Redis no ClickStack usando o receiver do Redis do OTel. Inclui um dataset de demonstração e um dashboard pré-configurado.

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:

# Testar conexão
redis-cli ping
# Saída esperada: PONG

# Testar o comando INFO (usado pelo coletor de métricas)
redis-cli INFO server
# Deve exibir informações do servidor Redis

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.yaml

receivers:
  redis:
    endpoint: "localhost:6379"
    collection_interval: 10s
    # Descomente se o Redis exigir autenticação
    # password: ${env:REDIS_PASSWORD}
    
    # Configure quais métricas coletar
    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

Na configuração personalizada, defina apenas novos receivers, processors e pipelines
Os processors memory_limiter e batch e o exporter clickhouse já estão definidos na configuração base do ClickStack — basta referenciá-los pelo nome
O processor resource define o atributo service.name obrigatório de acordo com as convenções semânticas do OpenTelemetry
Para produção com autenticação, armazene a senha em uma variável de ambiente: ${env:REDIS_PASSWORD}
Ajuste collection_interval de acordo com as suas necessidades (padrão de 10s; valores menores aumentam o volume de dados)
Para várias instâncias do Redis, personalize service.name para diferenciá-las (por exemplo, "redis-cache", "redis-sessions")

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:
    # ... configuração existente ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # Opcional: Se o Redis exigir autenticação
      # - REDIS_PASSWORD=your-redis-password
      # ... outras variáveis de ambiente ...
    volumes:
      - ./redis-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      # ... outros volumes ...
    # Se o Redis estiver no mesmo arquivo compose:
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    # Opcional: Habilitar autenticação
    # 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:

# Criar uma rede
docker network create monitoring

# Executar o Redis na rede
docker run -d --name redis --network monitoring redis:7-alpine

# Executar o ClickStack na mesma rede (atualize o endpoint para "redis:6379" na configuração)
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.

O intervalo de tempo do dataset de demonstração vai de 2025-10-20 00:00:00 a 2025-10-21 05:00:00. Certifique-se de que o intervalo de tempo no HyperDX corresponda a essa janela.Procure estes padrões interessantes:

06:00 - Aquecimento de cache (taxa de acerto baixa em alta)
14:30-14:45 - Pico de tráfego (muitas conexões de cliente, algumas rejeições)
20:00 - Pressão de memória (começam as evicções de chaves)

Dashboards 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.

a configuração do dashboard

Importe o dashboard pré-configurado

Abra o HyperDX e navegue até a seção Dashboards
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

Visualize o dashboard

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

Para o dataset de demonstração, defina o intervalo de tempo como 2025-10-20 05:00:00 - 2025-10-21 05:00:00 (UTC) (ajuste com base no seu fuso horário local). O dashboard importado não terá um intervalo de tempo especificado por padrão.

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

Indo para 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.

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

Pré-requisitos

​Verifique a conexão com o Redis

​Criar configuração personalizada do OTel collector

​Configure o ClickStack para carregar uma configuração personalizada

Opção 1: Docker Compose

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

​Verifique as métricas no HyperDX

​Dataset de demonstração

​Baixe o dataset de métricas de exemplo

​Inicie o ClickStack

​Carregue métricas no ClickStack

​Verifique as métricas no HyperDX

​Dashboards e visualização

​ a configuração do dashboard

​Importe o dashboard pré-configurado

​Visualize o dashboard

​Solução de problemas

​Configuração personalizada não está carregando

​As métricas não aparecem no HyperDX

​Erros de autenticação

​Problemas de conectividade de rede

​Próximos passos

​Indo para produção

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

Verifique a conexão com o Redis

Criar configuração personalizada do OTel collector

Configure o ClickStack para carregar uma configuração personalizada

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

Verifique as métricas no HyperDX

Dataset de demonstração

Baixe o dataset de métricas de exemplo

Inicie o ClickStack

Carregue métricas no ClickStack

Verifique as métricas no HyperDX

Dashboards e visualização

a configuração do dashboard

Importe o dashboard pré-configurado

Visualize o dashboard

Solução de problemas

Configuração personalizada não está carregando

As métricas não aparecem no HyperDX

Erros de autenticação

Problemas de conectividade de rede

Próximos passos

Indo para produção