ClickStack を使用した Redis メトリクスの監視

要約

このガイドでは、OpenTelemetry collector の Redis receiver を設定し、ClickStack で Redis のパフォーマンスメトリクスを監視する方法を説明します。次のことが行えるようになります。

Redis メトリクスを収集するように OTel collector を設定する
カスタム設定を使用して ClickStack をデプロイする
あらかじめ用意されたダッシュボードを使用して Redis のパフォーマンス（commands/sec、メモリ使用量、接続クライアント数、キャッシュ性能）を可視化する

本番環境の Redis を設定する前に連携をテストしたい場合のために、サンプルメトリクスを含むデモデータセットが用意されています。

所要時間: 5～10 分

既存の Redis との統合

このセクションでは、ClickStack の OTel collector に Redis receiver を構成し、既存の Redis 環境からメトリクスを ClickStack に送信する方法を説明します。

既存環境を設定する前に Redis メトリクス連携を試してみたい場合は、次のセクションで提供している事前設定済みのデモデータセットを使ってテストできます。

前提条件

稼働中の ClickStack インスタンス
Redis の既存インストール（バージョン 3.0 以降）
ClickStack から Redis へのネットワークアクセス（デフォルトポート 6379）
認証を有効にしている場合の Redis パスワード

Redis接続の確認

まず、Redisに接続できること、およびINFOコマンドが機能することを確認します：

# 接続テスト
redis-cli ping
# 期待される出力: PONG

# INFO コマンドのテスト（メトリクスコレクターで使用）
redis-cli INFO server
# Redis サーバー情報が表示されます

Redisで認証が必要な場合：

redis-cli -a <your-password> ping

一般的なRedisエンドポイント:

ローカル環境: localhost:6379
Docker：コンテナ名またはサービス名（例：redis:6379）を使用する
リモート: <redis-host>:6379

カスタムOTel collector設定を作成する

ClickStackでは、カスタム設定ファイルをマウントして環境変数を設定することで、ベースのOpenTelemetryコレクター設定を拡張できます。カスタム設定は、HyperDXがOpAMP経由で管理するベース設定にマージされます。

以下の設定で redis-metrics.yaml という名前のファイルを作成します:

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秒ごとにメトリクスを収集します
主要なパフォーマンス指標（コマンド、クライアント、メモリ、キー空間の統計情報）を収集します
OpenTelemetry semantic conventions に従って、必須の service.name リソース属性を設定します。
専用パイプライン経由でメトリクスを ClickHouse exporter に転送する

収集される主要メトリクス:

redis.commands.processed - 1秒あたりに処理されたコマンド数
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 - 拒否された接続数

注記

カスタム設定では、新しい receiver、processor、pipeline だけを定義します
memory_limiter と batch の各プロセッサおよび clickhouse エクスポーターは、ベースとなる ClickStack 構成ですでに定義されているため、名前を指定するだけで参照できます
resource プロセッサは、OpenTelemetry のセマンティック規約で必須とされる service.name 属性を設定します
本番環境で認証を有効にする場合は、パスワードを環境変数 ${env:REDIS_PASSWORD} に保存してください
必要に応じて collection_interval を調整します（デフォルトは 10 秒で、値を小さくするとデータ量が増加します）。
複数の Redis インスタンスがある場合は、それらを区別できるように service.name を設定します（例: "redis-cache"、"redis-sessions"）

ClickStackにカスタム設定を読み込むよう構成する

既存のClickStackデプロイメントでカスタムコレクター設定を有効にするには、次の手順を実行してください:

カスタム設定ファイルを /etc/otelcol-contrib/custom.config.yaml にマウントします
環境変数 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml を設定してください
ClickStack と Redis 間のネットワーク接続を確立する

オプション1: Docker Compose

ClickStackのデプロイメント設定を更新します：

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でオールインワンイメージを使用する場合：

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" \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one:latest

重要: Redisが別のコンテナで実行されている場合は、Dockerネットワーキングを使用してください：

# ネットワークを作成する
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" \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one:latest

HyperDXでメトリクスを確認する

設定完了後、HyperDXにログインし、メトリクスが正常に送信されていることを確認します：

Metrics Explorer に移動します
redis. で始まるメトリクス（例：redis.commands.processed、redis.memory.used）を検索します。
設定した収集間隔でメトリクスのデータポイントが表示されているはずです

デモ用データセット

本番環境を設定する前に Redis Metrics インテグレーションをテストしたいユーザー向けに、現実的な Redis Metrics のパターンを含むあらかじめ生成されたデータセットを提供しています。

サンプルメトリクスデータセットをダウンロードする

あらかじめ生成されたメトリクスファイルをダウンロードします（現実的なパターンを含む 24 時間分の Redis Metrics）:

# ゲージメトリクスをダウンロード（メモリ、断片化率） \{#expected-output-pong}
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/redis/redis-metrics-gauge.csv

# サムメトリクスをダウンロード（コマンド数、接続数、キー空間統計） \{#test-info-command-used-by-metrics-collector}
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) - キーの削除とキャッシュ性能の低下
日次トラフィックパターン - ビジネスタイムのピーク、夜間の低下、ランダムなマイクロスパイク

ClickStack を起動する

ClickStack インスタンスを起動します:

docker run -d --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one:latest

ClickStack が完全に起動するまで約 30 秒待ちます。

メトリクスを ClickStack にロードする

メトリクスを直接 ClickHouse にロードします:

# ゲージメトリクスをロード（メモリ、断片化）
cat redis-metrics-gauge.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

# サムメトリクスをロード（コマンド数、接続数、キー空間）
cat redis-metrics-sum.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"

HyperDX でメトリクスを確認する

読み込みが完了したら、メトリクスを確認する最も手早い方法は、あらかじめ用意されたダッシュボードを利用することです。

「Dashboards and visualization」セクションに進み、ダッシュボードをインポートして、すべての Redis Metrics を一度に確認します。

注記

デモデータセットの時間範囲は 2025-10-20 00:00:00 から 2025-10-21 05:00:00 です。HyperDX 側の時間範囲がこの時間帯に一致していることを確認してください。

次のような興味深いパターンを探してみてください:

06:00 - キャッシュウォーミング（低いヒット率が上昇していく）
14:30-14:45 - トラフィックスパイク（クライアント接続数の増加と一部の拒否）
20:00 - メモリプレッシャー（キー削除が始まる）

ダッシュボードと可視化

ClickStack で Redis の監視を始めるにあたり、Redis Metrics 用の基本的な可視化ダッシュボードを提供します。

ダッシュボード設定をダウンロード

用意済みダッシュボードをインポートする

HyperDX を開き、Dashboards セクションに移動します
右上の三点リーダーのメニューから Import Dashboard をクリックします

redis-metrics-dashboard.json ファイルをアップロードし、Finish Import をクリックします

ダッシュボードを表示する

ダッシュボードは、すべての可視化が事前設定された状態で作成されます。

注記

デモデータセットの場合は、タイムレンジを 2025-10-20 05:00:00 - 2025-10-21 05:00:00 (UTC) に設定してください（ローカルタイムゾーンに応じて調整してください）。インポートされたダッシュボードには、デフォルトではタイムレンジが指定されていません。

トラブルシューティング

カスタム設定が読み込まれない

環境変数 CUSTOM_OTELCOL_CONFIG_FILE が正しく設定されていることを確認してください。

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 <コンテナ名> cat /etc/otelcol-contrib/custom.config.yaml

HyperDX にメトリクスが表示されない

collector から Redis にアクセスできることを確認してください：

# ClickStackコンテナから \{#download-sum-metrics-commands-connections-keyspace-stats}
docker exec <clickstack-container> redis-cli -h <redis-host> ping
# 期待される出力: PONG

Redis の INFO コマンドが正常に動作することを確認します:

docker exec <clickstack-container> redis-cli -h <redis-host> INFO stats
# Redisの統計情報が表示されるはずです

有効な設定に Redis レシーバーが含まれていることを確認します。

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 "redis:"

コレクターのログにエラーが出ていないか確認してください：

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i redis
# 接続エラーまたは認証失敗を確認します \{#load-gauge-metrics-memory-fragmentation}

認証エラー

ログに認証エラーが表示されている場合:

# Redisが認証を要求することを確認する
redis-cli CONFIG GET requirepass

# 認証をテストする
redis-cli -a <password> ping

# ClickStack環境でパスワードが設定されていることを確認する
docker exec <clickstack-container> printenv REDIS_PASSWORD

パスワードを使用するように構成を更新します。

receivers:
  redis:
    endpoint: "redis:6379"
    password: ${env:REDIS_PASSWORD}

ネットワーク接続の問題

ClickStack が Redis に接続できない場合:

# 両方のコンテナが同じネットワーク上にあるか確認
docker network inspect <network-name>

# 接続性をテスト
docker exec <clickstack-container> ping redis
docker exec <clickstack-container> telnet redis 6379

Docker Compose ファイルまたは docker run コマンドで、両方のコンテナが同一のネットワーク上に置かれるように構成してください。

次のステップ

さらに踏み込んで試してみたい場合は、監視について次のことに取り組んでみてください：

重要なメトリクス（メモリ使用量のしきい値、接続数の上限、キャッシュヒット率の低下）に対するアラートを設定する
特定のユースケース（レプリケーション遅延、永続化パフォーマンス）向けの追加ダッシュボードを作成する
異なるエンドポイントやサービス名で receiver 設定を複製し、複数の Redis インスタンスを監視する

既存の Redis との統合​

前提条件​

Redis接続の確認​

カスタムOTel collector設定を作成する​

ClickStackにカスタム設定を読み込むよう構成する​

オプション1: Docker Compose​

オプション2: Docker run（オールインワンイメージ）​

HyperDXでメトリクスを確認する​

デモ用データセット​

サンプルメトリクスデータセットをダウンロードする​

ClickStack を起動する​

メトリクスを ClickStack にロードする​

HyperDX でメトリクスを確認する​

ダッシュボードと可視化​

ダッシュボード設定をダウンロード​

用意済みダッシュボードをインポートする​

ダッシュボードを表示する​

トラブルシューティング​

カスタム設定が読み込まれない​

HyperDX にメトリクスが表示されない​

認証エラー​

ネットワーク接続の問題​

次のステップ​