Monitoramento de logs do Redis com ClickStack

Integração com Redis existente

Esta seção explica como configurar sua instalação atual do Redis para enviar logs para o ClickStack, modificando a configuração do ClickStack OTel collector. Se quiser testar a integração com Redis antes de configurar seu próprio ambiente, você pode usar nossa configuração pré-configurada e os dados de exemplo na seção "conjunto de dados de demonstração".

Pré-requisitos

Instância do ClickStack em execução
Instalação existente de Redis (versão 3.0 ou mais recente)
Acesso aos arquivos de log do Redis

Verifique a configuração de logging do Redis

Primeiro, verifique a configuração de logging do Redis. Conecte-se ao Redis e verifique a localização do arquivo de log:

redis-cli CONFIG GET logfile

Locais comuns dos logs do Redis:

Linux (apt/yum): /var/log/redis/redis-server.log
macOS (Homebrew): /usr/local/var/log/redis.log
Docker: geralmente registra em stdout, mas pode ser configurado para gravar em /data/redis.log

Se o Redis estiver registrando em stdout, configure-o para gravar em um arquivo atualizando o redis.conf:

# Log to file instead of stdout
logfile /var/log/redis/redis-server.log

# Set log level (options: debug, verbose, notice, warning)
loglevel notice

Após alterar a configuração, reinicie o Redis:

# For systemd
sudo systemctl restart redis

# For Docker
docker restart <redis-container>

Criar uma configuração personalizada do OTel collector

O ClickStack permite estender a configuração base do OpenTelemetry Collector montando um arquivo de configuração personalizado e definindo uma variável de ambiente. A configuração personalizada é mesclada à configuração base gerenciada pelo HyperDX via OpAMP.

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

receivers:
  filelog/redis:
    include:
      - /var/log/redis/redis-server.log
    start_at: beginning
    operators:
      - type: regex_parser
        regex: '^(?P\d+):(?P\w+) (?P\d{2} \w+ \d{4} \d{2}:\d{2}:\d{2})\.\d+ (?P[.\-*#]) (?P.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%d %b %Y %H:%M:%S'
      
      - type: add
        field: attributes.source
        value: "redis"
      
      - type: add
        field: resource["service.name"]
        value: "redis-production"

service:
  pipelines:
    logs/redis:
      receivers: [filelog/redis]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

Esta configuração:

Lê os logs do Redis em seu local padrão
Faz o parsing do formato de log do Redis usando regex para extrair campos estruturados (pid, role, timestamp, log_level, message)
Adiciona o atributo source: redis para filtragem no HyperDX
Encaminha os logs para o ClickHouse exporter por meio de um pipeline dedicado

Configure o ClickStack para carregar uma configuração personalizada

Para habilitar uma configuração personalizada do collector 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
Montar o diretório de logs do Redis para que o collector possa lê-los

Opção 1: Docker Compose

Atualize a configuração da implantação do ClickStack:

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./redis-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/redis:/var/log/redis:ro
      # ... other volumes ...

Opção 2: Docker Run (Imagem all-in-one)

Se estiver usando a imagem all-in-one com Docker, execute:

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-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log/redis:/var/log/redis:ro \
  clickhouse/clickstack-all-in-one:latest

Verificando logs no HyperDX

Depois de configurar, faça login no HyperDX e verifique se os logs estão sendo recebidos:

Conjunto de dados de demonstração

Para usuários que querem testar a integração com o Redis antes de configurar seus sistemas de produção, fornecemos um conjunto de dados de exemplo com logs do Redis pré-gerados e padrões realistas.

Baixar o conjunto de dados de exemplo

Baixe o arquivo de log de exemplo:

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/redis/redis-server.log

Criar a configuração de teste do collector

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

cat > redis-demo.yaml << 'EOF'
receivers:
  filelog/redis:
    include:
      - /tmp/redis-demo/redis-server.log
    start_at: beginning  # Ler desde o início para os dados de demonstração
    operators:
      - type: regex_parser
        regex: '^(?P<pid>\d+):(?P<role>\w+) (?P<timestamp>\d{2} \w+ \d{4} \d{2}:\d{2}:\d{2})\.\d+ (?P<log_level>[.\-*#]) (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%d %b %Y %H:%M:%S'
      
      - type: add
        field: attributes.source
        value: "redis-demo"
      
      - type: add
        field: resource["service.name"]
        value: "redis-demo"

service:
  pipelines:
    logs/redis-demo:
      receivers: [filelog/redis]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

Executar o ClickStack com a configuração de demonstração

Execute o ClickStack com os logs e a configuração de demonstração:

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

Verifique os logs no HyperDX

Quando o ClickStack estiver em execução:

Abra o HyperDX e entre na sua conta (talvez seja necessário criar uma conta primeiro)
Vá para a visualização Busca e defina a fonte como Logs
Defina o intervalo de tempo como 2025-10-26 10:00:00 - 2025-10-29 10:00:00

Dashboards e visualizações

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

Baixar a configuração do dashboard

Baixar o arquivo de configuração do dashboard.

Importar 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-logs-dashboard.json e clique para concluir a importação.

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

Solução de problemas

Config personalizada não está sendo carregada

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

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE
# Saída esperada: /etc/otelcol-contrib/custom.config.yaml

Verifique se o arquivo de configuração personalizado está montado:

docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml
# Saída esperada: Deve exibir o tamanho do arquivo e as permissões

Veja o conteúdo da configuração personalizada:

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
# Deve exibir o conteúdo do seu redis-monitoring.yaml

Verifique se a configuração efetiva inclui o receiver filelog:

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog
# Deve exibir a configuração do seu receiver filelog/redis

Os logs não aparecem no HyperDX

Verifique se o Redis está gravando os logs em um arquivo:

redis-cli CONFIG GET logfile
# Saída esperada: Deve mostrar um caminho de arquivo, não uma string vazia
# Exemplo: 1) "logfile" 2) "/var/log/redis/redis-server.log"

Verifique se o Redis está gerando logs ativamente:

tail -f /var/log/redis/redis-server.log
# Deve exibir entradas de log recentes no formato Redis

Verifique se o collector consegue ler os logs:

docker exec <container> cat /var/log/redis/redis-server.log
# Deve exibir entradas de log do Redis

Verifique se há erros nos logs do collector:

docker exec <container> cat /etc/otel/supervisor-data/agent.log
# Procure mensagens de erro relacionadas ao filelog ou Redis

Se estiver usando o docker-compose, verifique os volumes compartilhados:

# Verifique se ambos os containers estão usando o mesmo volume
docker volume inspect <volume-name>
# Verifique se ambos os containers têm o volume montado

Logs não estão sendo processados corretamente

Verifique se o formato de log do Redis corresponde ao padrão esperado:

# Os logs do Redis devem ter este formato:
# 12345:M 28 Oct 2024 14:23:45.123 * Server started
tail -5 /var/log/redis/redis-server.log

Se os logs do Redis estiverem em um formato diferente, talvez seja necessário ajustar o padrão regex no operador regex_parser. O formato padrão é:

pid:role timestamp level message
Exemplo: 12345:M 28 Oct 2024 14:23:45.123 * Server started

Próximos passos

Configure alertas para métricas críticas (taxas de erro, limiares de latência)
Crie dashboards adicionais para casos de uso específicos (monitoramento de API, eventos de segurança)

Preparando para produção

Este guia se baseia no 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.