98 lines
7.8 KiB
Markdown
98 lines
7.8 KiB
Markdown
---
|
|
title: Micrometer — Naming meters / Conventions
|
|
source_type: official-doc
|
|
url: https://docs.micrometer.io/micrometer/reference/concepts/naming.html
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [ca-metrics-alerting, micrometer, naming-convention, prometheus, official-doc]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
related_branches: [feature-metrics-alerting-contract]
|
|
created: 2026-05-22
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# Micrometer — Naming meters / Conventions
|
|
|
|
> Layer: `raw/official-docs/` — Micrometer 공식 reference 의 naming convention verbatim. ca-tmpl 의 "metric naming = Micrometer dot.case default" 결정의 1차 spec 근거.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-metrics-alerting-contract]] | metric naming convention 으로 Micrometer dot.case default 채택 + unit suffix 는 Micrometer convention (`.seconds`/`.bytes`/`.total`) 강제 결정의 spec 근거 |
|
|
| [[raw/project-notes/ca-skeleton-operational-contract]] | §18. Control Plane Contract (Metrics / Alerting) 의 metric naming 채택안 — Micrometer dot.case |
|
|
|
|
## 컨텍스트
|
|
|
|
ca-tmpl 이 채택한 "**metric naming convention = Micrometer dot.case default. unit suffix 는 Micrometer convention (`.seconds`/`.bytes`/`.total`) 강제**" 의 spec 근거.
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://docs.micrometer.io/micrometer/reference/concepts/naming.html
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: Micrometer (VMware / Spring 생태계, Apache-2.0)
|
|
- 발행일: rolling docs
|
|
- 마지막 확인일: 2026-05-27
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§Naming meters] "Micrometer employs a naming convention that separates lowercase words with a `.` (dot) character."
|
|
|
|
> [§Naming meters] "Each Micrometer implementation for a monitoring system comes with a naming convention that transforms lowercase dot notation names to the monitoring system's recommended naming convention."
|
|
|
|
> [§Naming meters — example transformation] "registry.timer(\"http.server.requests\");" transforms to:
|
|
> - Prometheus: `http_server_requests_duration_seconds`
|
|
> - Atlas: `httpServerRequests`
|
|
> - Graphite: `http.server.requests`
|
|
> - InfluxDB: `http_server_requests`
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| MM-NAME-C1 | Micrometer 의 naming convention 은 lowercase word 를 dot (`.`) 으로 구분 | [§Naming meters] "Micrometer employs a naming convention that separates lowercase words with a `.` (dot) character." | `official-vendor-doc` | Micrometer API 로 등록되는 모든 meter 의 default naming | uppercase / camelCase 가 거부된다는 강한 뜻 아님 — convention 표현 |
|
|
| MM-NAME-C2 | 각 monitoring system 별 Micrometer 구현이 lowercase dot notation 을 해당 시스템 권장 naming convention 으로 자동 변환 | [§Naming meters] "Each Micrometer implementation for a monitoring system comes with a naming convention that transforms lowercase dot notation names to the monitoring system's recommended naming convention." | `official-vendor-doc` | Micrometer registry (Prometheus, Atlas, Graphite, InfluxDB 등) | 모든 monitoring system 이 자동 변환을 지원한다는 뜻 아님 — Micrometer 구현 존재하는 시스템 한정 |
|
|
| MM-NAME-C3 | 동일 Micrometer name `http.server.requests` 는 시스템 별로 다음과 같이 변환: Prometheus `http_server_requests_duration_seconds`, Atlas `httpServerRequests`, Graphite `http.server.requests`, InfluxDB `http_server_requests` | [§Naming meters — example transformation] "registry.timer(\"http.server.requests\");" → Prometheus: `http_server_requests_duration_seconds`, Atlas: `httpServerRequests`, Graphite: `http.server.requests`, InfluxDB: `http_server_requests` | `official-vendor-doc` | timer 타입 meter 의 시스템 별 노출 형식 | counter / gauge 의 변환 규칙이 동일하다는 뜻 아님 — 본 예시는 timer 한정 |
|
|
| MM-NAME-C4 | `.count`, `.total`, `.sum`, `.max` 같은 suffix 가 monitoring system 에 의해 자동 추가되며 meter name 에 직접 포함하지 말아야 한다 | (본 페이지 발췌에 명시 없음) | `needs-confirmation` | suffix 정책 | Micrometer reference 의 다른 페이지 (예: `concepts/timers`) 에서 별도 확인 필요 — 본 페이지 발췌만으로는 직접 인용 불가 |
|
|
| MM-NAME-C5 | base unit (seconds, bytes) 의 application 전역 일관성 유지 / TimeUnit handling 으로 시스템 별 unit suffix 자동 부착 | (본 페이지 발췌에 명시 없음) | `needs-confirmation` | unit handling | 본 페이지가 unit handling 을 다루지 않음 — `concepts/timers` 등 별도 페이지 필요 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것**:
|
|
- `MM-NAME-C1` ~ `C3`: Micrometer 의 lowercase dot naming convention, 시스템 별 자동 변환, `http.server.requests` 의 시스템 별 정확한 변환 결과
|
|
- **이 자료가 증명하지 않는 것**:
|
|
- `.count`/`.total`/`.sum`/`.max` 같은 suffix 의 자동 부착 규칙 (`MM-NAME-C4` — 본 페이지에 미명시, 다른 reference 페이지 필요)
|
|
- TimeUnit / base unit (seconds, bytes) handling 의 정확한 동작 (`MM-NAME-C5` — 별도 페이지)
|
|
- tag (label) 의 lowercase snake_case 권장이 Micrometer 공식 권장이라는 결론 (본 페이지 발췌 범위 밖)
|
|
- high-cardinality tag 금지 정책이 Micrometer 공식 권장이라는 결론 (별도 `concepts/cardinality` 필요)
|
|
- Spring Boot Actuator 가 Micrometer naming 을 default 로 채택한다는 결론 (Spring Boot reference 별도)
|
|
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
|
- ca-tmpl 의 unit suffix 강제 정책이 Micrometer 자동 변환 위에 추가 정책인지 vs 자동 변환만 신뢰하는지
|
|
- HikariCP / JVM / Tomcat 등 라이브러리 기본 meter naming 이 Spring Boot 3 에서 모두 dot.case 로 통일되었는지 (Spring Boot 3 reference 확인)
|
|
- Prometheus naming (`http_server_requests_seconds_*`) 의 정확한 _count/_sum/_bucket suffix 규칙 (Prometheus exposition format 별도)
|
|
|
|
## 메모 / Notes (내 프로젝트 해석)
|
|
|
|
> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.
|
|
|
|
- **표준 example (`MM-NAME-C3` 외 추론)**:
|
|
- HTTP latency: `http.server.requests` (Spring Boot 3 default) — Prometheus 에서 `http_server_requests_seconds_*` 또는 `http_server_requests_duration_seconds` 로 변환 (정확한 suffix 는 Spring Boot 3 / Micrometer 버전 의존, 별도 확인).
|
|
- DB pool: `hikaricp.connections.acquire` → `hikaricp_connections_acquire_seconds` (추론).
|
|
- JVM: `jvm.memory.used`, `jvm.gc.pause`.
|
|
- **tag convention**: lowercase, snake_case 권장 (Micrometer 관례, 본 페이지 직접 인용 아님). high-cardinality 금지 (user id, request id) — ca-tmpl Cardinality Bounds 표와 정합.
|
|
- **장점**: Spring Boot Actuator default, 사실상 JVM 생태계 표준. backend (Prometheus / Datadog / Wavefront / Atlas) 무관하게 동일 name 으로 작성 (`MM-NAME-C2`).
|
|
- **단점**: Prometheus naming (snake_case + `_total` suffix) 과 1:1 매핑이 자동 변환이라 직접 PromQL 작성 시 혼동 가능. tag name 도 monitoring system convention 변환됨.
|
|
- **ca-tmpl 과의 차이**: 100% 일치. Spring Boot 3 + Micrometer default 를 그대로 채택.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 raw:
|
|
- [[raw/official-docs/metric-otel-metrics-data-model-spec]] (OTel naming/attribute 비교)
|
|
- [[raw/official-docs/metric-google-sre-slo-burn-rate]] (alerting 정책)
|
|
- 인용하는 branch:
|
|
- [[raw/branch-notes/feature-metrics-alerting-contract]]
|
|
- 인용하는 project:
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]] (§18 Metrics / Alerting — Micrometer naming 채택)
|
|
- 인용한 wiki 요약: (미작성)
|