跳转到主内容
跳转到主内容

使用 ClickStack 监控 Redis 日志

摘要

使用 OTel filelog 接收器在 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 配置文件将其改为写入文件:

# 将日志记录到文件而非标准输出
logfile /var/log/redis/redis-server.log

# 设置日志级别（选项：debug、verbose、notice、warning）
loglevel notice

更改配置后,重新启动 Redis:

# 使用 systemd 时
sudo systemctl restart redis

# 使用 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 exporter
注意
  • 只需在自定义配置中定义新的 receiver 和 pipeline 即可
  • 处理器（memory_limiter、transform、batch）和导出器（clickhouse）已经在基础 ClickStack 配置中定义好，只需按名称引用它们即可。
  • time_parser 运算符从 Redis 日志中提取时间戳，以保留日志的原始时间
  • 此配置使用 start_at: beginning，在 collector 启动时读取所有已有日志，使你可以立即查看日志。对于生产环境的部署，如需在 collector 重启时避免重新摄取日志，请将其改为 start_at: end。

配置 ClickStack 加载自定义配置​

要在现有的 ClickStack 部署中启用自定义采集器配置，您必须：

  1. 将自定义配置文件挂载到路径 /etc/otelcol-contrib/custom.config.yaml
  2. 设置环境变量 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
  3. 挂载 Redis 日志目录，以便采集器能够读取这些日志
选项 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
注意

确保 ClickStack 采集器具有读取 Redis 日志文件的相应权限。在生产环境中,请使用只读挂载(:ro)并遵循最小权限原则。

在 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 启动并运行后：

  1. 打开 HyperDX 并登录到您的账户（可能需要先创建账户）
  2. 进入 Search 视图，将数据源设置为 Logs
  3. 将时间范围设置为 2025-10-26 10:00:00 - 2025-10-29 10:00:00
时区显示

HyperDX 会按浏览器的本地时区显示时间戳。演示数据覆盖的时间范围为 2025-10-27 10:00:00 - 2025-10-28 10:00:00 (UTC)。较宽的时间范围可以确保无论您位于哪个时区，都能看到演示日志。看到日志后，您可以将时间范围缩小到 24 小时，以获得更清晰的可视化效果。

日志视图
日志

仪表盘和可视化​

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

下载 仪表盘配置​

导入预构建仪表盘​

  1. 打开 HyperDX，并导航到 Dashboards 部分。
  2. 点击右上角省略号菜单中的 "Import Dashboard"。
导入仪表盘
  1. 上传 redis-logs-dashboard.json 文件并点击完成导入。
完成导入

仪表盘将会被创建，并包含所有预先配置好的可视化图表​

注意

对于演示数据集，将时间范围设置为 2025-10-27 10:00:00 - 2025-10-28 10:00:00 (UTC)（可根据本地时区进行调整）。导入的仪表盘默认不会指定时间范围。

示例仪表盘

故障排查​

自定义配置未生效​

检查环境变量是否已正确设置：

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 接收器：

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

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，请检查共享卷：

# 检查两个容器是否使用同一卷 \{#expected-output-etcotelcol-contribcustomconfigyaml}
docker volume inspect <volume-name>
# 验证两个容器均已挂载该卷 \{#expected-output-should-show-file-size-and-permissions}

日志解析不正确​

检查 Redis 日志格式是否符合预期模式：

# Redis 日志应类似如下： \{#should-show-your-filelogredis-receiver-configuration}
# 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 数据。