APM 기본 (Part 1: 개념과 도구)

APM (Application Performance Monitoring)
= 애플리케이션 성능을 실시간으로 모니터링

목적:
- 성능 병목 발견
- 장애 조기 감지
- 사용자 경험 최적화
- 리소스 사용량 추적

사용자 요청 하나를 추적한다고 생각해보세요:

[Metrics] → "지금 p95가 2초야, 뭔가 느려졌다" (감지)
[Traces]  → "느린 요청을 따라가보니 PaymentService에서 병목" (위치 파악)
[Logs]    → "PaymentService 로그: DB connection timeout" (원인 확인)

세 가지를 조합해야 문제를 빠르게 해결할 수 있습니다.

💡 실무 팁:
- 마이크로서비스 → RED로 서비스 상태 모니터링
- 인프라/DB/캐시 → USE로 리소스 상태 모니터링
- 둘 다 함께 보는 게 이상적

평균 응답 시간: 200ms
P50 (중앙값): 150ms    ← 절반의 요청이 이 시간 내 완료
P95 (95 백분위수): 500ms  ← 중요!
P99: 1000ms             ← 꼬리 지연(tail latency)

P95가 높다 = 일부 사용자가 느린 경험

⚠️ "평균"의 함정:
  요청 100개 중 99개가 10ms, 1개가 9,010ms → 평균 100ms
  → "평균 100ms"는 정상처럼 보이지만, 1%는 9초를 기다림
  → 반드시 P95/P99를 함께 봐야 합니다.

RPS (Requests Per Second): 초당 요청 수
TPM (Transactions Per Minute): 분당 트랜잭션 수

예:
- 평균 RPS: 100
- 피크 RPS: 500 (트래픽 급증 시)

용량 산정 공식 (Little's Law):
  동시 요청 수 = RPS × 평균 응답 시간(초)
  
  100 RPS × 0.2초 = 20 동시 요청
  → 스레드 풀 20개면 이론상 커버 (여유분 고려해 40~50)

오류율 = (실패한 요청 / 전체 요청) × 100

예:
- 전체 요청: 10,000
- 실패: 50
- 오류율: 0.5%

목표: 오류율 < 0.1% (SLA에 따라 다름)

⚠️ 주의:
  - 5xx만 세면 안 됩니다. 타임아웃(504), 서킷브레이커(503)도 에러입니다.
  - 4xx 중에서도 429(Rate Limit), 408(Timeout)은 서버 측 문제 징후입니다.
  - 비즈니스 에러(결제 실패 등)도 별도 카운터로 추적해야 합니다.

┌──────────────────────────────────────────┐
│                Grafana                    │  ← 시각화/대시보드/알림
├───────────┬───────────┬──────────────────┤
│ Prometheus│   Loki    │     Tempo        │
│ (Metrics) │  (Logs)   │   (Traces)       │
├───────────┴───────────┴──────────────────┤
│          OpenTelemetry Collector          │  ← 수집/변환/라우팅
├──────────────────────────────────────────┤
│    Spring Boot + Micrometer + OTel SDK   │  ← 계측
└──────────────────────────────────────────┘

<!-- pom.xml -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

# application.yml
management:
  endpoints:
    web:
      exposure:
        include: health, info, prometheus, metrics, env
      base-path: /actuator
  endpoint:
    health:
      show-details: when_authorized   # 인증된 사용자에게만 상세 정보
      show-components: when_authorized
      probes:
        enabled: true                  # K8s liveness/readiness 프로브
  metrics:
    tags:
      application: ${spring.application.name}
      environment: ${spring.profiles.active:local}
    distribution:
      percentiles-histogram:
        http.server.requests: true     # 히스토그램 활성화 (p95/p99 계산용)
      percentiles:
        http.server.requests: 0.5, 0.95, 0.99
      sla:
        http.server.requests: 100ms, 500ms, 1s, 5s  # SLO 버킷

@Configuration
@EnableWebSecurity
public class ActuatorSecurityConfig {
    
    @Bean
    public SecurityFilterChain actuatorSecurity(HttpSecurity http) throws Exception {
        return http
            .securityMatcher("/actuator/**")
            .authorizeHttpRequests(auth -> auth
                // health와 prometheus는 내부 네트워크에서 인증 없이 접근 가능
                .requestMatchers("/actuator/health/liveness").permitAll()
                .requestMatchers("/actuator/health/readiness").permitAll()
                .requestMatchers("/actuator/prometheus").hasIpAddress("10.0.0.0/8")
                // 나머지는 ADMIN 역할 필요
                .anyRequest().hasRole("ADMIN")
            )
            .httpBasic(Customizer.withDefaults())
            .build();
    }
}

@Component
public class PaymentGatewayHealthIndicator implements HealthIndicator {
    
    private final PaymentGatewayClient paymentClient;
    private final CircuitBreaker circuitBreaker;
    
    @Override
    public Health health() {
        try {
            // 결제 게이트웨이 ping (타임아웃 2초)
            PaymentStatus status = paymentClient.healthCheck();
            
            if (status.isHealthy()) {
                return Health.up()
                    .withDetail("gateway", "PG사 연동 정상")
                    .withDetail("latency_ms", status.getLatencyMs())
                    .build();
            }
            
            return Health.down()
                .withDetail("gateway", "PG사 응답 이상")
                .withDetail("reason", status.getReason())
                .build();
                
        } catch (Exception e) {
            return Health.down()
                .withDetail("gateway", "PG사 연결 불가")
                .withException(e)
                .build();
        }
    }
}

{
  "status": "UP",
  "components": {
    "db": { "status": "UP", "details": { "database": "PostgreSQL" } },
    "redis": { "status": "UP" },
    "paymentGateway": {
      "status": "UP",
      "details": { "gateway": "PG사 연동 정상", "latency_ms": 45 }
    }
  }
}

@Component
@RequiredArgsConstructor
public class OrderMetrics {
    
    private final MeterRegistry registry;
    
    // === Counter: 누적 횟수 (증가만 가능) ===
    public void recordOrderCreated(String paymentMethod) {
        registry.counter("orders.created",
            "payment_method", paymentMethod,  // 결제수단별 분류
            "channel", "web"                  // 채널별 분류
        ).increment();
    }
    
    // === Gauge: 현재 값 (증감 가능) ===
    // AtomicInteger 등을 바인딩하면 현재 상태를 추적
    private final AtomicInteger activeOrders = new AtomicInteger(0);
    
    @PostConstruct
    public void initGauges() {
        Gauge.builder("orders.active", activeOrders, AtomicInteger::get)
            .description("현재 처리 중인 주문 수")
            .register(registry);
    }
    
    // === Timer: 실행 시간 측정 ===
    public <T> T measureOrderProcessing(Supplier<T> task) {
        return registry.timer("orders.processing.duration",
            "type", "sync"
        ).record(task);
    }
    
    // === DistributionSummary: 값의 분포 ===
    public void recordOrderAmount(double amount) {
        DistributionSummary.builder("orders.amount")
            .description("주문 금액 분포")
            .baseUnit("won")
            .publishPercentiles(0.5, 0.95, 0.99)
            .publishPercentileHistogram()
            .maximumExpectedValue(10_000_000.0)
            .register(registry)
            .record(amount);
    }
}

💡 실무 원칙: 대부분의 경우 Histogram을 쓰세요.
  - 서비스가 여러 인스턴스로 스케일되면 Summary는 합산할 수 없습니다.
  - publishPercentileHistogram()을 켜면 Prometheus에서 
    histogram_quantile()로 p95/p99를 구할 수 있습니다.

// ❌ 나쁜 예: 사용자 ID를 태그에 넣음 (카디널리티 폭발!)
registry.counter("api.requests", "user_id", userId);
// 사용자 100만명 × API 50개 = 5천만 시계열 → Prometheus 사망

// ✅ 좋은 예: 낮은 카디널리티 태그만 사용
registry.counter("api.requests", 
    "endpoint", "/api/orders",    // 50개 이내
    "method", "GET",              // 5종
    "status", "200"               // 10종 이내
);
// 50 × 5 × 10 = 2,500 시계열 → 안전

┌─────────────────────────────────────┐
│ Level 1: Overview (전체 서비스 상태)  │  ← NOC/온콜 엔지니어가 항상 보는 화면
│   - 전체 에러율, p95, 서비스 맵      │
├─────────────────────────────────────┤
│ Level 2: Service (개별 서비스 상세)   │  ← 문제 발생 시 드릴다운
│   - RED 메트릭, 엔드포인트별 분포     │
├─────────────────────────────────────┤
│ Level 3: Resource (인프라/리소스)     │  ← 병목 원인 파악
│   - CPU/메모리/GC/커넥션 풀/슬로우쿼리│
└─────────────────────────────────────┘

1. Traffic Light (Red/Yellow/Green)
   - 각 서비스의 에러율 기반 상태 신호등
   
2. p95 Latency 추이 (시계열 그래프)
   - 엔드포인트별 p95, SLO 라인과 겹쳐서 표시
   
3. Error Rate 추이
   - 5xx rate, 서킷브레이커 트립 횟수
   
4. Saturation 게이지
   - CPU, 힙 메모리, 커넥션 풀 사용률

5. 최근 배포/변경 이벤트 (Annotation)
   - 배포 시점을 그래프에 표시 → 성능 변화와 배포의 상관관계 파악

✅ Spring Boot Actuator + Prometheus 엔드포인트 활성화
✅ /health, /prometheus 엔드포인트 확인
✅ Prometheus scrape 설정 추가
✅ Grafana에 Spring Boot 템플릿 대시보드 import (ID: 12900)

✅ 커스텀 비즈니스 메트릭 3~5개 추가 (주문 수, 결제 성공률 등)
✅ SLO 기반 알림 2~3개 설정 (p95 > 1s, error rate > 1%)
✅ 커넥션 풀/스레드 풀 메트릭 대시보드 추가
✅ 구조 로깅(Structured Logging) 전환 시작

✅ 분산 트레이싱 도입 (OpenTelemetry + Tempo/Jaeger)
✅ Log ↔ Trace 연결 (traceId를 로그에 포함)
✅ 3계층 대시보드 완성
✅ 온콜 Runbook에 대시보드 링크 + 조치 가이드 포함
✅ 정기 리뷰: 월 1회 알림 품질 점검 (노이즈 비율 < 20%)