> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 ClickStack 监控 Redis 指标

> 使用 ClickStack 监控 Redis 指标

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Info>
  **简而言之**

  使用 OTel Redis receiver 在 ClickStack 中监控 Redis 性能指标。包含演示数据集和预置仪表板。
</Info>

<div id="existing-redis">
  ## 与现有 Redis 集成
</div>

本节介绍如何配置现有的 Redis 部署：通过为 ClickStack OTel collector 配置 Redis receiver，将指标发送到 ClickStack。

如果你想在配置自己现有的环境之前先测试 Redis 指标集成，可以在[下一节](#demo-dataset)中使用我们预先配置的演示数据集。

<div id="prerequisites">
  ##### 前置条件
</div>

* 正在运行的 ClickStack 实例
* 已有的 Redis 安装 (3.0 或更高版本)
* ClickStack 到 Redis 的网络访问 (默认端口 6379)
* 如果启用了身份验证，则需要 Redis 密码

<Steps>
  <Step>
    #### 验证 Redis 连接

    首先，确认你可以连接到 Redis，并且 `INFO` 命令能够正常执行：

    ```bash theme={null}
    # 测试连接
    redis-cli ping
    # 预期输出：PONG

    # 测试 INFO 命令（由指标收集器使用）
    redis-cli INFO server
    # 应显示 Redis 服务器信息
    ```

    如果 Redis 启用了身份验证：

    ```bash theme={null}
    redis-cli -a <your-password> ping
    ```

    **常见的 Redis 端点：**

    * **本地安装**：`localhost:6379`
    * **Docker**：使用容器名称或服务名称 (例如 `redis:6379`)
    * **远程**：`<redis-host>:6379`
  </Step>

  <Step>
    #### 创建自定义 OTel collector 配置

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

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

    ```yaml title="redis-metrics.yaml" theme={null}
    receivers:
      redis:
        endpoint: "localhost:6379"
        collection_interval: 10s
        # 如果 Redis 需要身份验证，请取消注释
        # password: ${env:REDIS_PASSWORD}
        
        # 配置要收集的指标
        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
    ```

    此配置：

    * 连接到 `localhost:6379` 上的 Redis (请根据你的部署调整端点)
    * 每 10 秒采集一次指标
    * 采集关键性能指标 (命令、客户端、内存、keyspace 统计信息)
    * **按照 [OpenTelemetry 语义约定](https://opentelemetry.io/docs/specs/semconv/resource/#service) 设置必需的 `service.name` 资源属性**
    * 通过专用管道将指标路由到 ClickHouse exporter

    **采集的关键指标：**

    * `redis.commands.processed` - 每秒处理的命令数
    * `redis.clients.connected` - 已连接的客户端数量
    * `redis.clients.blocked` - 因阻塞调用而被阻塞的客户端数量
    * `redis.memory.used` - Redis 已使用的内存字节数
    * `redis.memory.peak` - 峰值内存占用
    * `redis.keyspace.hits` - 成功的键查找次数
    * `redis.keyspace.misses` - 失败的键查找次数 (用于计算缓存命中率)
    * `redis.keys.expired` - 已过期的键数量
    * `redis.keys.evicted` - 因内存压力而被驱逐的键数量
    * `redis.connections.received` - 接收到的连接总数
    * `redis.connections.rejected` - 被拒绝的连接数

    <Note>
      - 你只需在自定义配置中定义新的 receivers、processors 和 pipelines
      - `memory_limiter` 和 `batch` processors 以及 `clickhouse` exporter 已在基础 ClickStack 配置中定义，你只需按名称引用它们
      - `resource` processor 会按照 OpenTelemetry 语义约定设置必需的 `service.name` 属性
      - 如果在生产环境中启用身份验证，请将密码存储在环境变量中：`${env:REDIS_PASSWORD}`
      - 请根据需要调整 `collection_interval` (默认值为 10 秒；较低的值会增加数据量)
      - 如果有多个 Redis 实例，请自定义 `service.name` 以便区分它们 (例如：`"redis-cache"`、`"redis-sessions"`)
    </Note>
  </Step>

  <Step>
    #### 配置 ClickStack 以加载自定义配置

    要在现有的 ClickStack 部署中启用自定义 collector 配置，您需要：

    1. 将自定义配置文件挂载到 `/etc/otelcol-contrib/custom.config.yaml`
    2. 设置环境变量 `CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml`
    3. 确保 ClickStack 与 Redis 之间的网络连通

    ##### 选项 1：Docker Compose

    更新您的 ClickStack 部署配置：

    ```yaml theme={null}
    services:
      clickstack:
        # ... 现有配置 ...
        environment:
          - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
          # 可选：如果 Redis 需要身份验证
          # - REDIS_PASSWORD=your-redis-password
          # ... 其他环境变量 ...
        volumes:
          - ./redis-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
          # ... 其他卷 ...
        # 如果 Redis 在同一个 compose 文件中：
        depends_on:
          - redis

      redis:
        image: redis:7-alpine
        ports:
          - "6379:6379"
        # 可选：启用身份验证
        # command: redis-server --requirepass your-redis-password
    ```

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

    如果使用一体化镜像并通过 `docker run` 运行：

    ```bash theme={null}
    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
    ```

    **重要：** 如果 Redis 在另一个容器中运行，请使用 Docker 网络：

    ```bash theme={null}
    # 创建网络
    docker network create monitoring

    # 在该网络中运行 Redis
    docker run -d --name redis --network monitoring redis:7-alpine

    # 在同一网络中运行 ClickStack（在配置中将端点更新为 "redis:6379"）
    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
    ```
  </Step>

  <Step>
    #### 在 HyperDX 中验证指标

    配置完成后，登录 HyperDX 并确认指标是否已开始流入：

    1. 打开指标浏览器
    2. 搜索以 `redis.` 开头的指标 (例如：`redis.commands.processed`、`redis.memory.used`)
    3. 你应会看到指标数据点按你配置的采集间隔持续出现
  </Step>
</Steps>

<div id="demo-dataset">
  ## 演示数据集
</div>

对于想在配置生产系统之前先测试 Redis 指标 集成的用户，我们提供了一个预生成的数据集，其中包含逼真的 Redis 指标 变化模式。

<Steps>
  <Step>
    #### 下载样本指标数据集

    下载预生成的指标文件 (24 小时的 Redis 指标 数据，包含逼真的变化模式) ：

    ```bash theme={null}
    # 下载 gauge 指标（内存、碎片率）
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/redis/redis-metrics-gauge.csv

    # 下载 sum 指标（命令、连接、keyspace 统计）
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/redis/redis-metrics-sum.csv
    ```

    该数据集包含以下逼真模式：

    * **缓存预热事件 (06:00) ** - 命中率从 30% 升至 80%
    * **流量突增 (14:30-14:45) ** - 流量激增 5 倍，并伴随连接压力
    * **内存压力 (20:00) ** - 出现 key 驱逐，缓存性能下降
    * **每日流量模式** - 工作时段达到高峰、夜间回落、随机出现小尖峰
  </Step>

  <Step>
    #### 启动 ClickStack

    启动一个 ClickStack 实例：

    ```bash theme={null}
    docker run -d --name clickstack-demo \
      -p 8080:8080 -p 4317:4317 -p 4318:4318 \
      clickhouse/clickstack-all-in-one:latest
    ```

    等待大约 30 秒，让 ClickStack 完全启动。
  </Step>

  <Step>
    #### 将指标加载到 ClickStack 中

    将指标直接加载到 ClickHouse：

    ```bash theme={null}
    # 加载 gauge 指标（内存、碎片）
    cat redis-metrics-gauge.csv | docker exec -i clickstack-demo \
      clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

    # 加载 sum 指标（命令、连接、keyspace）
    cat redis-metrics-sum.csv | docker exec -i clickstack-demo \
      clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"
    ```
  </Step>

  <Step>
    #### 在 HyperDX 中验证指标

    加载完成后，查看指标的最快方式是使用预置仪表盘。

    继续前往[仪表盘和可视化](#dashboards)部分，导入仪表盘并一次查看全部 Redis 指标。

    <Note>
      演示数据集的时间范围为 2025-10-20 00:00:00 到 2025-10-21 05:00:00。请确保 HyperDX 中的时间范围与该时间窗口一致。

      请留意以下有代表性的模式：

      * **06:00** - 缓存预热 (命中率从较低水平开始上升)
      * **14:30-14:45** - 流量突增 (客户端连接数高，出现部分拒绝)
      * **20:00** - 内存压力 (开始出现 key 驱逐)
    </Note>
  </Step>
</Steps>

<div id="dashboards">
  ## 仪表盘与可视化
</div>

为帮助你开始使用 ClickStack 监控 Redis，我们提供了 Redis 指标 所需的关键可视化内容。

<Steps>
  <Step>
    #### <TrackedLink href={'/zh/examples/redis-metrics-dashboard.json'} download="redis-metrics-dashboard.json" eventName="docs.redis_metrics_monitoring.dashboard_download">下载</TrackedLink>仪表盘配置
  </Step>

  <Step>
    #### 导入预构建仪表盘

    1. 打开 HyperDX 并进入 仪表盘 部分
    2. 点击右上角省略号菜单中的 **Import Dashboard**

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/zXCQbzXFHfeD9FBK/images/clickstack/import-dashboard.png?fit=max&auto=format&n=zXCQbzXFHfeD9FBK&q=85&s=eace17d7f86efbec4d3151bbf428941a" alt="导入仪表盘按钮" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

    3. 上传 `redis-metrics-dashboard.json` 文件，然后点击 **Finish Import**

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/zXCQbzXFHfeD9FBK/images/clickstack/import-redis-metrics-dashboard.png?fit=max&auto=format&n=zXCQbzXFHfeD9FBK&q=85&s=ebc17b313b885c4b71c794bfab64e132" alt="完成导入对话框" width="3814" height="1914" data-path="images/clickstack/import-redis-metrics-dashboard.png" />
  </Step>

  <Step>
    #### 查看仪表盘

    导入后，仪表盘会创建完成，且所有可视化都已预先配置好：

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/huP88Vza7bEG09HU/images/clickstack/redis-metrics-dashboard.png?fit=max&auto=format&n=huP88Vza7bEG09HU&q=85&s=51e7421e576cfd2406eda6e1a0890da8" alt="Redis 指标 仪表盘" width="3814" height="1914" data-path="images/clickstack/redis-metrics-dashboard.png" />

    <Note>
      对于演示数据集，请将时间范围设置为 **2025-10-20 05:00:00 - 2025-10-21 05:00:00 (UTC)** (请根据你的本地时区调整) 。导入的仪表盘默认不会指定时间范围。
    </Note>
  </Step>
</Steps>

<div id="troubleshooting">
  ## 故障排查
</div>

<div id="troubleshooting-not-loading">
  ### 自定义配置未正确加载
</div>

请确认环境变量 `CUSTOM_OTELCOL_CONFIG_FILE` 设置正确：

```bash theme={null}
docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE
```

检查自定义配置文件是否已挂载到 `/etc/otelcol-contrib/custom.config.yaml`：

```bash theme={null}
docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml
```

查看自定义 config 内容，确认其可正常读取：

```bash theme={null}
docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
```

<div id="no-metrics">
  ### HyperDX 中没有显示任何指标
</div>

确认采集器可以访问 Redis：

```bash theme={null}
# 从 ClickStack 容器中执行
docker exec <clickstack-container> redis-cli -h <redis-host> ping
# 预期输出：PONG
```

检查 Redis INFO 命令是否能正常运行：

```bash theme={null}
docker exec <clickstack-container> redis-cli -h <redis-host> INFO stats
# 应显示 Redis 统计信息
```

确认生效的配置中包含你的 Redis receiver：

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 "redis:"
```

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

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i redis
# 查找连接错误或身份验证失败
```

<div id="auth-errors">
  ### 身份验证错误
</div>

如果您在日志中看到身份验证错误：

```bash theme={null}
# 验证 Redis 是否需要身份验证
redis-cli CONFIG GET requirepass

# 测试身份验证
redis-cli -a <password> ping

# 确保在 ClickStack 环境中已设置密码
docker exec <clickstack-container> printenv REDIS_PASSWORD
```

更新配置，使用该密码：

```yaml theme={null}
receivers:
  redis:
    endpoint: "redis:6379"
    password: ${env:REDIS_PASSWORD}
```

<div id="network-issues">
  ### 网络连接问题
</div>

如果 ClickStack 无法连接到 Redis：

```bash theme={null}
# 检查两个容器是否在同一网络中
docker network inspect <network-name>

# 测试连通性
docker exec <clickstack-container> ping redis
docker exec <clickstack-container> telnet redis 6379
```

确保在 Docker Compose 文件或 `docker run` 命令中，将两个容器置于同一网络中。

<div id="next-steps">
  ## 后续步骤
</div>

* 为关键指标设置[告警](/zh/clickstack/features/alerts) (如内存使用量阈值、连接数限制、缓存命中率下降)
* 针对特定用例创建更多仪表盘 (如复制延迟、持久化性能)
* 通过复制 receiver 配置并使用不同的端点和服务名称，监控多个 Redis 实例

<div id="going-to-production">
  ## 生产环境部署
</div>

本指南在 ClickStack 内置的 OpenTelemetry Collector 基础上进行了扩展，便于快速完成设置。对于生产环境部署，我们建议运行您自己的 OTel Collector，并将数据发送到 ClickStack 的 OTLP 端点。有关生产环境配置，请参阅[发送 OpenTelemetry 数据](/zh/clickstack/ingesting-data/opentelemetry)。