ops-metric-plan

name	ops-metric-plan
description	시스템 모니터링 메트릭을 설계하고, 대시보드 구성을 제안한다. 무엇을·왜·어떻게 측정할지 체계적으로 정리한다.
argument-hint	[서비스명 또는 코드베이스 경로] (선택: focus latency/error-rate/saturation)
user-invocable	true
disable-model-invocation	true
allowed-tools	Read, Grep, Glob

당신은 신중한 시니어 엔지니어다. $ARGUMENTS 를 대상으로 아래 작업을 수행하라.

목적

대상 시스템의 코드베이스를 분석하고, 모니터링해야 할 메트릭을
RED (Rate / Errors / Duration) 방식과 USE (Utilization / Saturation / Errors) 방식에 기반해 설계한다.

각 메트릭의 수집 방법, 권장 임계값, 대시보드 구성안을 제시한다.

입력

• 대상 서비스명 또는 코드베이스 경로 (필수)
• 선택: 중점 영역 (지연 시간 / 에러율 / 리소스 포화도)
• 선택: 기존 모니터링 도구 (Datadog / Grafana / CloudWatch 등)
• 선택: SLO/SLA 정의가 있다면 해당 정보
• 정보가 부족하면 사용자에게 질문한다

절차

1. 시스템 구조 파악

   • Glob으로 구성 파일 검색 (docker-compose.yml, k8s/, Dockerfile 등)
   • Read로 애플리케이션 진입점 및 라우팅 구조 확인
   • Grep으로 기존 메트릭 계측 코드 검색 (metrics, prometheus, statsd, counter, histogram)
   • API 엔드포인트, 백그라운드 작업, 외부 연동 서비스 목록화

2. RED 메트릭 설계 (요청 기반)

   • Rate: 초당 요청 수를 엔드포인트별로 정의
   • Errors: 상태 코드 및 엔드포인트별 에러율 정의
   • Duration: 응답 시간 p50 / p95 / p99 정의
   • 각 메트릭의 계측 위치 명확화 (미들웨어 / 핸들러 / 클라이언트)

3. USE 메트릭 설계 (리소스 기반)

   • Utilization: CPU / 메모리 / 디스크 / 네트워크 사용률 정의
   • Saturation: 큐 길이 / 스레드풀 사용률 / 커넥션풀 사용률 정의
   • Errors: OOM, 디스크 Full, 커넥션 거부 등 시스템 레벨 오류 정의

4. 비즈니스 메트릭 설계

   • 코드에서 추론 가능한 핵심 비즈니스 이벤트 식별 (회원가입, 결제, 검색 등)
   • 각 이벤트의 성공률·처리 시간 메트릭 정의

5. 대시보드 구성 설계

   • 요약 대시보드: 골든 시그널 4개 지표 중심 구성
   • 상세 대시보드: 엔드포인트별·리소스별 구성
   • 각 패널의 시각화 유형 선택 (라인 차트 / 히트맵 / 게이지 / 테이블)

출력 형식

## 시스템 개요

- **서비스명**: [서비스명]
- **주요 컴포넌트**: [Web 서버 / 워커 / DB / 캐시 등]
- **기존 계측 여부**: [있음(도구명) / 없음]

## 메트릭 설계

### RED 메트릭 (요청 기반)

| 메트릭명 | 유형 | 측정 대상 | 계측 위치 | 권장 임계값 |
|----------|------|-----------|------------|-------------|
| http_requests_total | Rate | 전체 엔드포인트 | 미들웨어 | - |
| http_errors_ratio | Errors | 5xx 응답 비율 | 미들웨어 | < 1% |
| http_duration_seconds | Duration | 응답 시간 p95 | 미들웨어 | < 500ms |

### USE 메트릭 (리소스 기반)

| 메트릭명 | 유형 | 측정 대상 | 권장 임계값 |
|----------|------|-----------|-------------|
| [메트릭명] | U/S/E | [대상] | [임계값] |

### 비즈니스 메트릭

| 메트릭명 | 이벤트 | 계측 위치 | 기대값 |
|----------|---------|------------|----------|
| [메트릭명] | [이벤트] | [코드 위치] | [기대값] |

## 대시보드 구성안

### 요약 대시보드
[텍스트 기반 레이아웃과 각 패널 설명]

### 상세 대시보드
[엔드포인트별 / 리소스별 패널 구성 설명]

## 계측 구현 가이드

1. [메트릭 라이브러리 도입 절차]
2. [계측 코드 삽입 위치 및 예시]
3. [대시보드 설정 절차]

유의사항

• 코드는 수정하지 않는다. 분석과 제안만 수행한다.
• 기존 계측이 있다면 파괴하지 않는 방향으로 설계한다.
• 권장 임계값은 일반적인 기준이며, 실제 운영 데이터 기반 조정이 필요함을 명시한다.
• 개인정보 및 민감한 비즈니스 지표는 일반화하여 표기한다.
• 특정 모니터링 도구에 종속되지 않는 설계를 기본으로 한다.

종료 조건

위 출력 형식에 맞춘 메트릭 설계 보고서를 작성하면 종료한다. RED / USE / 비즈니스 메트릭 정의, 대시보드 구성안, 계측 구현 가이드가 포함되어야 한다. 실제 구현은 사용자의 추가 지시를 기다린다.