使用 ClickStack 监控 Redis 日志

与现有 Redis 集成

本节介绍如何通过修改 ClickStack OTel collector 的配置，将现有 Redis 安装配置为向 ClickStack 发送日志。如果你想在配置自己现有的环境之前先测试 Redis 集成，可以在“演示数据集”部分使用我们预先配置的环境和示例数据进行测试。

前置条件

正在运行的 ClickStack 实例
已安装 Redis (3.0 或更高版本)
可访问 Redis 日志文件

验证 Redis 日志配置

首先，检查 Redis 的日志配置。连接到 Redis，并查看日志文件的位置：

redis-cli CONFIG GET logfile

常见的 Redis 日志位置：

Linux (apt/yum)：/var/log/redis/redis-server.log
macOS (Homebrew)：/usr/local/var/log/redis.log
Docker：通常会输出到 stdout，但也可以配置为写入 /data/redis.log

如果 Redis 将日志输出到 stdout，可通过修改 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

更改配置后，重新启动 Redis：

# For systemd
sudo systemctl restart redis

# For Docker
docker restart <redis-container>

创建自定义 OTel collector 配置

ClickStack 支持通过挂载自定义配置文件并设置环境变量来扩展基础 OpenTelemetry Collector 配置。自定义配置会与 HyperDX 通过 OpAMP 管理的基础配置合并。

创建一个名为 redis-monitoring.yaml 的文件，内容如下：

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

此配置：

从 Redis 日志的标准位置读取日志
使用正则表达式解析 Redis 的日志格式，提取结构化字段 (pid、role、timestamp、log_level、message)
添加 source: redis 属性，便于在 HyperDX 中进行过滤
通过专用管道将日志路由到 ClickHouse 导出器

配置 ClickStack 以加载自定义配置

要在现有的 ClickStack 部署中启用自定义 collector 配置，你必须：

将自定义配置文件挂载到 /etc/otelcol-contrib/custom.config.yaml
设置环境变量 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
挂载 Redis 的日志目录，以便 collector 读取这些日志

选项 1：Docker Compose

更新 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 ...

选项 2：Docker Run (一体化镜像)

如果你使用 Docker 的一体化镜像，请运行：

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

在 HyperDX 中验证日志

配置完成后，登录 HyperDX，确认日志已开始流入：

演示数据集

对于希望在配置生产系统之前先测试 Redis 集成的用户，我们提供了一个预先生成的 Redis 日志示例数据集，其中包含逼真的模式。

下载示例数据集

下载示例日志文件：

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

创建测试 collector 配置

创建一个名为 redis-demo.yaml 的文件，内容如下：

cat > redis-demo.yaml << 'EOF'
receivers:
  filelog/redis:
    include:
      - /tmp/redis-demo/redis-server.log
    start_at: beginning  # 演示数据从开头开始读取
    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

使用演示配置运行 ClickStack

使用演示日志和配置运行 ClickStack：

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

在 HyperDX 中验证日志

ClickStack 运行后：

打开 HyperDX 并登录你的账户 (你可能需要先创建账户)
进入搜索视图，并将 source 设置为 Logs
将时间范围设置为 2025-10-26 10:00:00 - 2025-10-29 10:00:00

仪表盘与可视化

为帮助你快速开始使用 ClickStack 监控 Redis，我们提供了用于 Redis 日志的关键可视化内容。

下载仪表盘配置

下载仪表盘配置文件。

导入预构建仪表盘

打开 HyperDX，进入“仪表盘”部分。
点击右上角省略号菜单中的“Import Dashboard”。

上传 redis-logs-dashboard.json 文件，然后点击 Finish Import。

系统将创建一个已预先配置好所有可视化的仪表盘

故障排查

自定义配置未生效

确认环境变量已正确设置：

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE
# 预期输出：/etc/otelcol-contrib/custom.config.yaml

检查自定义配置文件是否已成功挂载：

docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml
# 预期输出：应显示文件大小和权限

查看自定义配置的内容：

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
# 应显示 redis-monitoring.yaml 的内容

检查已生效的配置中是否包含 filelog receiver：

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog
# 应显示您的 filelog/redis receiver 配置

HyperDX 中没有显示日志

请确保 Redis 正在将日志写入文件：

redis-cli CONFIG GET logfile
# 预期输出：应显示文件路径，而非空字符串
# 示例：1) "logfile" 2) "/var/log/redis/redis-server.log"

检查 Redis 是否正在输出日志：

tail -f /var/log/redis/redis-server.log
# 应显示 Redis 格式的最新日志条目

确认 collector 能够读取日志：

docker exec <container> cat /var/log/redis/redis-server.log
# 应显示 Redis 日志条目

检查 collector 日志中是否有错误：

docker exec <container> cat /etc/otel/supervisor-data/agent.log
# 查找与 filelog 或 Redis 相关的错误信息

如果使用 docker-compose，请确认共享卷配置是否正确：

# 检查两个容器是否使用相同的卷
docker volume inspect <volume-name>
# 验证两个容器是否均已挂载该卷

日志未正确解析

确认 Redis 日志格式与预期模式一致：

# Redis 日志格式应如下所示：
# 12345:M 28 Oct 2024 14:23:45.123 * Server started
tail -5 /var/log/redis/redis-server.log

如果你的 Redis 日志格式不同，可能需要调整 regex_parser 操作符中的正则表达式模式。标准格式如下：

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

后续步骤

为关键指标 (错误率、延迟阈值) 配置告警
针对特定用例 (API 监控、安全事件) 创建更多仪表盘

投入生产环境

本指南基于 ClickStack 内置的 OpenTelemetry Collector，帮助您快速完成设置。对于生产环境部署，我们建议自行运行 OTel Collector，并将数据发送到 ClickStack 的 OTLP 端点。有关生产环境配置，请参阅发送 OpenTelemetry 数据。