ClickStack으로 Redis 메트릭 모니터링

기존 Redis와의 통합

이 섹션에서는 ClickStack OTel collector를 Redis 수신기로 구성해, 기존 Redis 환경에서 ClickStack으로 메트릭을 전송하도록 설정하는 방법을 설명합니다.

기존 환경을 직접 구성하기 전에 Redis Metrics 통합을 테스트하려면, 다음 섹션에서 미리 구성된 데모 데이터셋로 먼저 테스트할 수 있습니다.

사전 요구 사항

실행 중인 ClickStack 인스턴스
기존 Redis 설치본(버전 3.0 이상)
ClickStack에서 Redis로의 네트워크 접근(기본 포트 6379)
인증이 enabled된 경우 Redis 비밀번호

Redis 연결 확인

먼저 Redis에 연결할 수 있는지, 그리고 INFO 명령이 정상적으로 작동하는지 확인합니다:

# Test connection
redis-cli ping
# Expected output: PONG

# Test INFO command (used by metrics collector)
redis-cli INFO server
# Should display Redis server information

Redis 인증이 필요한 경우:

redis-cli -a <your-password> ping

일반적으로 사용되는 Redis 엔드포인트:

로컬 설치: localhost:6379
Docker: 컨테이너 이름 또는 서비스 이름을 사용합니다(예: redis:6379)
원격: <redis-host>:6379

사용자 지정 OTel collector 구성 만들기

ClickStack에서는 사용자 지정 설정 파일을 마운트하고 환경 변수를 설정해 기본 OpenTelemetry collector 구성을 확장할 수 있습니다. 사용자 지정 구성은 OpAMP를 통해 HyperDX가 관리하는 기본 구성과 머지됩니다.

다음 구성으로 redis-metrics.yaml 파일을 생성하십시오:

redis-metrics.yamlyaml

receivers:
  redis:
    endpoint: "localhost:6379"
    collection_interval: 10s
    # Uncomment if Redis requires authentication
    # password: ${env:REDIS_PASSWORD}
    
    # Configure which metrics to collect
    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 semantic conventions에 따라 필수 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 - 거부된 연결 수

ClickStack가 사용자 지정 구성을 로드하도록 설정

기존 ClickStack 배포에서 사용자 지정 collector 구성을 활성화하려면 다음 작업을 수행해야 합니다:

사용자 지정 구성 파일을 /etc/otelcol-contrib/custom.config.yaml에 마운트합니다
환경 변수 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml를 설정합니다
ClickStack와 Redis 간 네트워크 연결이 되는지 확인합니다

옵션 1: Docker Compose

ClickStack 배포 구성을 업데이트합니다:

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # Optional: If Redis requires authentication
      # - REDIS_PASSWORD=your-redis-password
      # ... other environment variables ...
    volumes:
      - ./redis-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      # ... other volumes ...
    # If Redis is in the same compose file:
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    # Optional: Enable authentication
    # 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" \
  clickhouse/clickstack-all-in-one:latest

중요: Redis가 다른 컨테이너에서 실행되고 있다면 Docker 네트워킹을 사용하세요:

# Create a network
docker network create monitoring

# Run Redis on the network
docker run -d --name redis --network monitoring redis:7-alpine

# Run ClickStack on the same network (update endpoint to "redis:6379" in config)
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

HyperDX에서 메트릭 확인

구성이 완료되면 HyperDX에 로그인한 다음 메트릭이 정상적으로 수집되는지 확인합니다:

Metrics 탐색기로 이동합니다
redis.로 시작하는 메트릭을 검색합니다(예: redis.commands.processed, redis.memory.used)
구성한 수집 인터벌에 따라 메트릭 데이터 포인트가 표시되어야 합니다

데모 데이터세트

프로덕션 시스템을 구성하기 전에 Redis Metrics 통합을 테스트하려는 사용자를 위해, 실제와 유사한 Redis Metrics 패턴이 포함된 미리 생성된 데이터셋을 제공합니다.

샘플 메트릭 데이터셋 다운로드

미리 생성된 메트릭 파일을 다운로드합니다(실제와 유사한 패턴이 포함된 24시간 분량의 Redis Metrics):

# 게이지 메트릭 다운로드(메모리, 단편화 비율)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/redis/redis-metrics-gauge.csv

# 합계 메트릭 다운로드(명령, 연결, 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) - 키 eviction 및 캐시 성능 저하
일일 트래픽 패턴 - 업무 시간대 피크, 저녁 시간대 감소, 불규칙한 미세 스파이크

ClickStack 시작

ClickStack 인스턴스를 시작합니다:

docker run -d --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-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"

# 합계 메트릭 로드(명령, 연결, keyspace)
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를 한 번에 확인하십시오.

대시보드 및 시각화

ClickStack으로 Redis 모니터링을 시작할 수 있도록 Redis Metrics용 핵심 시각화를 제공합니다.

대시보드 구성 다운로드

대시보드 구성 파일 다운로드.

사전 구축된 대시보드 가져오기

HyperDX를 열고 Dashboards 섹션으로 이동합니다
오른쪽 상단의 줄임표 메뉴에서 Import Dashboard를 클릭합니다

redis-metrics-dashboard.json 파일을 업로드하고 Finish Import를 클릭합니다

대시보드 보기

대시보드는 모든 시각화가 사전 구성된 상태로 생성됩니다:

문제 해결

사용자 지정 구성이 로드되지 않는 경우

환경 변수 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 <container-name> cat /etc/otelcol-contrib/custom.config.yaml

HyperDX에 메트릭이 표시되지 않는 경우

collector에서 Redis에 접근할 수 있는지 확인하세요:

# ClickStack 컨테이너에서 실행
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:"

collector 로그에서 오류가 있는지 확인하세요:

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i redis
# 연결 오류 또는 인증 실패 항목을 확인하세요

인증 오류

로그에 인증 관련 오류가 표시되면:

# 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 명령에서 두 컨테이너가 동일한 네트워크를 사용하도록 설정하십시오.

다음 단계

중요한 메트릭(메모리 사용량 임계값, 연결 제한, 캐시 적중률 저하)에 대한 알림을 설정합니다
특정 사용 사례(복제 지연, 영속성 성능)에 맞는 추가 대시보드를 생성합니다
서로 다른 엔드포인트와 서비스 이름을 사용하도록 수신기 구성을 복제하여 여러 Redis 인스턴스를 모니터링합니다

운영 환경으로 전환하기

이 가이드는 빠르게 설정할 수 있도록 ClickStack에 내장된 OpenTelemetry Collector를 확장해 사용합니다. 운영 환경에 배포할 때는 자체 OTel Collector를 실행하고 데이터를 ClickStack의 OTLP 엔드포인트로 전송하는 것을 권장합니다. 운영 환경 구성은 OpenTelemetry 데이터 전송을 참조하십시오.