모니터링

Claude Code의 사용 현황, 성능, 에러를 실시간으로 모니터링하여 안정적인 서비스 운영을 보장합니다. 다양한 메트릭과 알림을 통해 문제를 사전에 감지하고 대응할 수 있습니다.

대시보드 개요

📊 주요 메트릭

  • API 요청 수: 시간대별, 사용자별 요청 통계
  • 응답 시간: 평균 및 P95 레이턴시
  • 에러율: 에러 유형별 분류 및 추세
  • 토큰 사용량: 입력/출력 토큰 소비 현황
  • 활성 사용자: 일일/월간 활성 사용자 수

실시간 모니터링

CLI 모니터링 명령어

# 실시간 상태 확인
claude monitor --live

# 최근 1시간 통계
claude stats --period 1h

# 에러 로그 확인
claude logs --level error --tail 50

# 성능 메트릭
claude metrics --type performance

웹 대시보드

직관적인 웹 인터페이스를 통한 모니터링:

  • 실시간 차트 및 그래프
  • 커스터마이징 가능한 대시보드
  • 드릴다운 분석 기능
  • 데이터 내보내기 지원

로그 관리

{
  "logging": {
    "level": "info",
    "outputs": [
      {
        "type": "file",
        "path": /var/log/claude-code/",
        "rotation": {
          "maxSize": "100MB",
          "maxFiles": 10,
          "compress": true
        }
      },
      {
        "type": "syslog",
        "facility": "local0"
      },
      {
        "type": "elasticsearch",
        "endpoint": "https://logs.company.com",
        "index": "claude-code-logs"
      }
    ],
    "structuredLogging": true,
    "includeContext": true
  }
}

📝 로그 레벨

  • DEBUG: 상세한 디버깅 정보
  • INFO: 일반적인 정보성 메시지
  • WARN: 잠재적 문제 경고
  • ERROR: 에러 발생 기록
  • CRITICAL: 심각한 오류

성능 모니터링

응답 시간 추적

# 응답 시간 통계
claude perf stats --metric latency

# 느린 요청 분석
claude perf slow-queries --threshold 5s --limit 20

# 병목 현상 진단
claude perf bottlenecks --analyze

리소스 사용률

메트릭 설명 임계값
API 레이턴시 평균 응답 시간 < 2초
에러율 실패한 요청 비율 < 1%
토큰 효율성 요청당 평균 토큰 모니터링만
동시 접속 활성 세션 수 계획별 상이

알림 설정

{
  "alerts": {
    "rules": [
      {
        "name": "high_error_rate",
        "condition": "error_rate > 5%",
        "duration": "5m",
        "severity": "critical",
        "actions": ["email", "slack", "pagerduty"]
      },
      {
        "name": "slow_response",
        "condition": "p95_latency > 5s",
        "duration": "10m",
        "severity": "warning",
        "actions": ["slack"]
      },
      {
        "name": "quota_exceeded",
        "condition": "daily_tokens > quota * 0.9",
        "severity": "warning",
        "actions": ["email"]
      }
    ],
    "channels": {
      "email": {
        "recipients": ["ops@company.com"]
      },
      "slack": {
        "webhook": "https://hooks.slack.com/...",
        "channel": "#claude-alerts"
      }
    }
  }
}

사용자 활동 추적

활동 보고서

# 사용자별 활동 요약
claude report user-activity --period "last-30-days"

# 가장 활발한 사용자
claude report top-users --metric requests --limit 10

# 사용 패턴 분석
claude analyze usage-patterns --group-by hour-of-day

감사 추적

모든 중요 활동을 추적하고 기록:

  • 파일 수정 내역
  • 실행된 명령어
  • API 호출 세부사항
  • 설정 변경 이력

통합 모니터링

Prometheus 통합

# prometheus.yml
scrape_configs:
  - job_name: 'claude-code'
    static_configs:
      - targets: ['localhost:9090']
    metrics_path: '/metrics'
    scrape_interval: 15s

Grafana 대시보드

사전 구성된 Grafana 대시보드 제공:

  • 실시간 메트릭 시각화
  • 커스텀 차트 생성
  • 알림 규칙 설정
  • 팀 대시보드 공유

APM 도구 연동

{
  "apm": {
    "provider": "datadog",
    "apiKey": "${DD_API_KEY}",
    "service": "claude-code",
    "environment": "production",
    "tags": [
      "team:engineering",
      "version:1.2.3"
    ]
  }
}

인시던트 대응

🚨 인시던트 관리 프로세스

  1. 감지: 자동 알림 또는 사용자 보고
  2. 분류: 심각도 및 영향 범위 평가
  3. 대응: 즉각적인 조치 수행
  4. 해결: 근본 원인 해결
  5. 사후 분석: 개선 사항 도출

런북 예제

# 높은 에러율 대응 런북

# 1. 현재 상태 확인
claude status --detailed
claude logs --level error --last 10m

# 2. 일시적 완화
claude config set rate-limit 50
claude config set retry-policy aggressive

# 3. 근본 원인 분석
claude analyze errors --group-by type
claude trace --request-id $ERROR_ID

# 4. 복구 확인
claude monitor --metric error-rate --watch

보고서 생성

# 월간 사용 보고서
claude report monthly --format pdf --output report-2024-01.pdf

# 팀별 분석 보고서
claude report team-usage --group-by department --export csv

# SLA 준수 보고서
claude report sla --period "Q1-2024" --include-incidents

# 자동 보고서 스케줄링
claude schedule report --type weekly --email team@company.com

최적화 권장사항

💡 모니터링 모범 사례

  • 기준선 설정: 정상 상태의 메트릭 기준선 정의
  • 점진적 알림: 경고부터 시작하여 단계적 에스컬레이션
  • 노이즈 감소: 의미 있는 알림만 설정
  • 정기 검토: 알림 규칙 및 임계값 주기적 조정
  • 자동화: 반복적인 대응 작업 자동화

다음 단계

다음 튜토리얼 →