MOPL 커스텀 메트릭 통합 명세

기준일: 2026-07-23

기준 소스: 현재 작업 트리의 Micrometer 계측 코드와 Prometheus/Grafana 설정

커스텀 메트릭_v1

1. 문서 목적

이 문서는 MOPL 애플리케이션에 실제 구현된 커스텀 메트릭의 이름, 타입, 태그와 집계 의미를 한곳에 정리한 기준 문서다.

기존 문서의 "수집 후보"나 담당자별 작업 계획이 아니라 다음 내용을 설명한다.

현재 애플리케이션이 실제로 기록하는 메트릭
Java의 Micrometer 이름과 Prometheus에 노출되는 이름
각 Counter, Timer, Gauge가 증가하거나 변경되는 시점
고정 태그 조합의 초기값 등록 여부
다중 App 인스턴스에서 올바르게 집계하는 방법
현재 구현하지 않은 항목과 해석 시 주의사항

메트릭을 시각화한 Grafana 화면과 각 Panel의 의미는 Grafana 페이지에서 별도로 설명한다.

2. 수집 구조

MOPL 애플리케이션
  -> Micrometer가 메트릭 기록
  -> Actuator의 /actuator/prometheus로 노출
  -> Prometheus가 App 인스턴스별로 5초마다 수집
  -> Grafana가 Prometheus 데이터를 PromQL로 조회

현재 구성은 다음과 같다.

항목	현재 설정
Micrometer Registry	`micrometer-registry-prometheus`
메트릭 엔드포인트	`/actuator/prometheus`
Prometheus Job	`mopl-app`
로컬 수집 대상	`app:8080`, `app-2:8080`
수집 주기	5초
Prometheus	`http://localhost:9090`
Grafana	`http://localhost:3000`

Spring이 이미 제공하는 실행 메트릭은 같은 의미의 커스텀 메트릭으로 중복 구현하지 않았다.

Batch Job과 Step의 실행 시간: Spring Batch 기본 메트릭 사용
Kafka Listener 처리 횟수와 시간: Spring Kafka 기본 메트릭 사용
업무 처리 건수, 현재 연결 수, Redis 동기화 결과 등 Spring 기본 메트릭으로 알 수 없는 값만 mopl.*로 구현