애플리케이션 메트릭: 미터와 메트릭명

미터 생성

마이크로미터에서 Meter를 생성하는 두 가지 방법이 있습니다:

1. 플루언트 빌더: 상세한 설정이 필요할 때
2. 축약 구문: 간단하게 생성할 때

플루언트 빌더 vs 축약 구문

플루언트 빌더는 라이브러리에서 사용하기 좋고, 축약 구문은 마이크로서비스에서 간결한 코드를 유지할 때 적합합니다.

기본 단위 정보는 모니터링 차트에서 가독성을 높이는 데 도움이 됩니다. 예를 들어 '2147483648 바이트'보다 '2GB'가 훨씬 보기 좋죠.

모니터링 시스템이 기본 단위 정보를 지원하지 않더라도 그라파나(grafana) 같은 차트 도구를 이용하면 사용자 인터페이스를 통해 수동으로 단위를 선택할 수 있고, 단위에 따라 자동 조절 기능을 수행합니다.

코드 예제

플루언트 빌더 방식

Counter counter = Counter.builder("requests")
    .tag("status", "200")
    .tags("method", "GET", "outcome", "SUCCESS")
    .description("http requests")
    .baseUnit("requests")
    .register(registry);

축약 구문 방식

Counter counter = registry.counter("requests",
    "status", "200", "method", "GET", "outcome", "SUCCESS");

미터를 생성하려면 두 방식 모두 이름과 태그를 반드시 지정해야 합니다.

메트릭명

메트릭명 작성 원칙

메트릭을 최대한 활용하려면 메트릭명을 적절히 선정하고 태그를 취합해야 합니다. 상시 혹은 특정 시기에 의미 있는 집계 수치를 나타내는 모든 태그가 취합 대상입니다.

좋은 메트릭명 설계

메트릭명은 영숫자 단어들로 구성하며 마침표로 구분합니다. 좋은 메트릭명은 백과 정보를 충분히 제공하며 메트릭명만 선택해도 의미 있는 값을 얻을 수 있어야 합니다.

올바른 예시

// 명확하고 구체적인 메트릭명 사용
registry.counter("database.queries", "db", "users");
registry.counter("http.requests", "uri", "/api/users");

예를 들어 http.server.requests 메트릭은 애플리케이션, 클라우드 서비스 리전, API 엔드포인트, HTTP 메서드, 응답 상태 코드 등의 태그를 포함합니다. 이 모든 태그를 고유하게 조합해 측정 결과를 집계하면 애플리케이션 스택 전반에 걸쳐 이뤄지는 모든 상호작용의 처리 결과를 산출할 수 있습니다.

피해야 할 메트릭명 설계

잘못된 예시

아래 예시처럼 모호한 메트릭명을 사용하면 문제가 발생합니다.

// 나쁜 예시 - 모호한 메트릭명
registry.counter("calls", "type", "database", "db", "users");
registry.counter("calls", "type", "http", "uri", "/api/users");

calls 메트릭을 선택할 때 데이터베이스 호출과 HTTP 요청 수가 합산된 값이 조회됩니다. 이 메트릭은 태그 차원에서 세부적으로 조회하지 않으면 쓸모가 없습니다.

네이밍 컨벤션과 필터링

MeterFilter 활용

네임스페이스를 통일하면 모니터링 시스템의 UI와 대시보드 도구에서 메트릭을 알맞게 순서대로 볼 수 있습니다. 또한 MeterFilter를 이용해 메트릭을 그룹 단위로 제어할 때 편리합니다.

아래 예시처럼 jvm.gc로 시작하는 모든 메트릭을 비활성화시키려면 다음과 같이 사용할 수 있습니다:

MeterRegistry registry = ...;
registry.config().meterFilter(MeterFilter.denyNameStartsWith("jvm.gc"));

모니터링 시스템마다 권장 명명 규칙은 다르고, 일부 규칙은 시스템 간에 서로 호환되지 않습니다. 마이크로미터는 영숫자 단어를 마침표로 연결하는 명명 규칙을 따르며, 구현 시 대상 모니터링 시스템에 맞는 명명 규칙이 함께 제공됩니다.

이 명명 규칙은 메트릭명과 태그에 포함된 특수문자를 확인하고 대상 시스템에 따라 적절히 처리합니다. 명명 규칙의 역할은 단순히 관용적인 외형을 지정하는 것에 그치지 않고, 엘라스틱서치는 마침표를 인덱스의 계층 구조로 인식합니다. 만일 http.server.requests와 http.client.requests 두 메트릭을 그대로 사용한다면, 엘라스틱서치 인덱싱을 처리할 때 문제가 됩니다.

사용자 정의 명명 규칙

MeterRegistry의 기본 명명 규칙은 사용자가 원하는 방식으로 오버라이드할 수 있습니다. 아래 예시는 NamingConvention 인터페이스를 이용해 사용자 명명 규칙을 설정합니다.

registry.config()
    .namingConvention(new NamingConvention() {
        @Override
        public String name(String name, Meter.Type type, String baseUnit) {
            String camelCased = NamingConvention.snakeCase.name(name, type, baseUnit);
            return baseUnit == null ? camelCased : camelCased + "_" + baseUnit;
        }
    });

이 예시는 메트릭명 뒤에 단위를 붙이는 사용자 정의 명명 규칙을 보여줍니다.

고유 태그와 비용 고려사항

고유 태그가 늘어날 때마다 스토리지 비용뿐만 아니라 쿼리 수행 비용도 시간적, 자원적인 면에서 함께 증가합니다. 쿼리 결과를 집계할 때 데이터가 늘어나기 때문입니다.

태그 설계 시 주의사항

태그값은 null이나 공백이 아니어야 합니다. 마이크로미터는 일부 상황에서 빈 태그값을 지원하기도 합니다(예: 데이터로그 레지스트리). 하지만 모든 모니터링 시스템이 빈 태그값을 지원하는 것은 아니므로, 다른 시스템으로 이전할 때 문제가 될 수 있습니다.