llm-wiki/raw/official-docs/resilience4j-micrometer-module.md

---
title: Resilience4j — Micrometer Module (Tagged Metrics for CircuitBreaker / Retry / Bulkhead / RateLimiter)
source_type: official-doc
url: https://resilience4j.readme.io/docs/micrometer
archive_url:
related_projects: []
related_branches: [feature-outbound-http-client-baseline, feature-metrics-alerting-contract]
tags: [resilience4j, micrometer, metrics, circuit-breaker, retry, bulkhead, rate-limiter, thread-pool-bulkhead, prometheus, observability, official-doc]
status: raw
confidence: high
created: 2026-05-27
last_reviewed: 2026-05-27
---

# Resilience4j — Micrometer Module (Tagged Metrics for CircuitBreaker / Retry / Bulkhead / RateLimiter)

> Layer: `raw/official-docs/` — Resilience4j 공식 docs "Micrometer" 페이지 verbatim.
> outbound HTTP client 의 CircuitBreaker/Retry/Bulkhead 가 Prometheus 로 노출되는 metric 이름·tag·state 의 1차 근거.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-outbound-http-client-baseline]] | D4 — 외부 호출에 Resilience4j CircuitBreaker + Retry 적용 시 metric 이 자동 노출되는 mechanism 의 공식 근거 (`resilience4j.circuitbreaker.calls`, `kind`/`name` tag 등) |
| [[raw/branch-notes/feature-metrics-alerting-contract]] | Prometheus alerting rule 의 base metric (calls/state/concurrent.calls/queue.depth/available.permissions) 명명 규약 |

## 컨텍스트

ca-tmpl 계열 프로젝트의 outbound HTTP client (RestClient + Resilience4j) 는 호출 결과를 Prometheus 로 노출해 SLO/alerting 의 기반으로 삼는다. 본 자료는 Resilience4j 의 Micrometer 모듈이 자동 생성하는 metric 의 정확한 이름·tag·state vocabulary 를 verbatim 으로 보존하기 위한 raw. circuitbreaker.state 의 5개 state ("closed", "open", "half_open", "forced_open", "disabled") 와 calls 의 kind tag ("successful", "failed", "ignored") 가 alerting rule 의 label matcher 기준.

## 출처 / Source

- 원본 URL: https://resilience4j.readme.io/docs/micrometer
- 아카이브 URL: (미수집)
- 저자 / 조직: Resilience4j project (community-maintained, official module 문서)
- 발행일: rolling docs (current = 2.x)
- 마지막 확인일: 2026-05-27

## 왜 저장했는지 / Why archived

Outbound HTTP client baseline 결정에서 "관측 가능성은 Resilience4j Micrometer 모듈을 그대로 사용한다" 는 선택의 근거. Prometheus query / Grafana panel / alerting rule 모두 본 페이지의 metric 명명을 그대로 쓰기 때문에 verbatim 보존 필요.

## 핵심 인용 / Key quotes (verbatim)

> [§Micrometer] "Resilience4j provides a module for Micrometer which supports most popular monitoring systems like InfluxDB or Prometheus."

> [§CircuitBreaker Metrics] "The following code snippet shows how to bind CircuitBreaker metrics to a MeterRegistry."

> [§CircuitBreaker Metrics] "resilience4j.circuitbreaker.calls" with tags: "kind=\"failed\" kind=\"successful\" kind=\"ignored\"" and "name=\"backendA\""

> [§CircuitBreaker Metrics] "resilience4j.circuitbreaker.state" is a Gauge with states: "closed" "open" "half_open" "forced_open" "disabled"

> [§Retry Metrics] "TaggedRetryMetrics.ofRetryRegistry(retryRegistry).bindTo(meterRegistry);"

> [§Bulkhead Metrics] "resilience4j.bulkhead.available.concurrent.calls" - "The number of available permissions"

> [§ThreadPoolBulkhead Metrics] "resilience4j.bulkhead.queue.depth" measures "The queue depth. The number of tasks waiting to be executed"

> [§RateLimiter Metrics] "resilience4j.ratelimiter.available.permissions" and "resilience4j.ratelimiter.waiting.threads"

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| R4J-MICROMETER-C1 | Resilience4j 는 Micrometer 모듈을 제공하며 이는 InfluxDB, Prometheus 등 주요 monitoring system 으로의 노출을 지원한다 | [§Micrometer] "Resilience4j provides a module for Micrometer which supports most popular monitoring systems like InfluxDB or Prometheus." | `official-vendor-doc` | Resilience4j 2.x + Micrometer 1.x | 특정 monitoring system 의 정확한 scrape 설정/dashboard 는 본 인용 범위 밖 |
| R4J-MICROMETER-C2 | CircuitBreaker metric 은 `MeterRegistry` 에 bind 해서 노출하며, 호출 결과는 `resilience4j.circuitbreaker.calls` 라는 metric 으로 노출되고 `kind` (successful/failed/ignored) 와 `name` (instance 명) tag 가 붙는다 | [§CircuitBreaker Metrics] "The following code snippet shows how to bind CircuitBreaker metrics to a MeterRegistry." + "resilience4j.circuitbreaker.calls" with tags: "kind=\"failed\" kind=\"successful\" kind=\"ignored\"" and "name=\"backendA\"" | `official-vendor-doc` | Tagged*Metrics binder 또는 spring-boot-starter auto-config 사용 시 | Spring Boot starter 가 자동으로 bind 한다는 뜻은 본 인용에서는 명시 안 됨 — starter 별 페이지 참조 필요 |
| R4J-MICROMETER-C3 | CircuitBreaker state 는 `resilience4j.circuitbreaker.state` 라는 Gauge 로 노출되며 가능한 state 는 5개: `closed`, `open`, `half_open`, `forced_open`, `disabled` | [§CircuitBreaker Metrics] "resilience4j.circuitbreaker.state" is a Gauge with states: "closed" "open" "half_open" "forced_open" "disabled" | `official-vendor-doc` | Resilience4j CircuitBreaker | state transition latency / failure rate threshold 등 다른 metric 은 별도 인용 필요 |
| R4J-MICROMETER-C4 | Retry metric 은 `TaggedRetryMetrics.ofRetryRegistry(retryRegistry).bindTo(meterRegistry)` 패턴으로 등록한다 | [§Retry Metrics] "TaggedRetryMetrics.ofRetryRegistry(retryRegistry).bindTo(meterRegistry);" | `official-vendor-doc` | Resilience4j Retry + Micrometer 수동 binder | spring-boot-starter 사용 시 자동 bind 여부는 본 인용 범위 밖 |
| R4J-MICROMETER-C5 | Bulkhead 는 `resilience4j.bulkhead.available.concurrent.calls` metric 으로 남은 permission 수를 노출한다 | [§Bulkhead Metrics] "resilience4j.bulkhead.available.concurrent.calls" - "The number of available permissions" | `official-vendor-doc` | Semaphore 기반 Bulkhead | ThreadPoolBulkhead 의 metric 명은 다름 (별도 C6 참조) |
| R4J-MICROMETER-C6 | ThreadPoolBulkhead 의 큐 깊이는 `resilience4j.bulkhead.queue.depth` metric 으로 노출되며 "큐에서 실행 대기 중인 task 수" 를 의미한다 | [§ThreadPoolBulkhead Metrics] "resilience4j.bulkhead.queue.depth" measures "The queue depth. The number of tasks waiting to be executed" | `official-vendor-doc` | ThreadPoolBulkhead | core thread pool size / max thread pool size 의 metric 명은 본 인용 범위 밖 |
| R4J-MICROMETER-C7 | RateLimiter 는 `resilience4j.ratelimiter.available.permissions` (남은 permission) 과 `resilience4j.ratelimiter.waiting.threads` (대기 thread 수) 두 metric 을 노출한다 | [§RateLimiter Metrics] "resilience4j.ratelimiter.available.permissions" and "resilience4j.ratelimiter.waiting.threads" | `official-vendor-doc` | Resilience4j RateLimiter | refresh period / limit-for-period 의 metric 노출 여부는 본 인용 범위 밖 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `R4J-MICROMETER-C1`: Micrometer 모듈의 Prometheus/InfluxDB 지원 사실
  - `R4J-MICROMETER-C2`: CircuitBreaker calls metric 명 + kind/name tag vocabulary
  - `R4J-MICROMETER-C3`: CircuitBreaker state 의 5개 정확한 state 이름
  - `R4J-MICROMETER-C4`: Retry metric binder API 정확한 호출 형태
  - `R4J-MICROMETER-C5`: Bulkhead 의 available concurrent calls metric 명
  - `R4J-MICROMETER-C6`: ThreadPoolBulkhead 의 queue depth metric 명 + 의미
  - `R4J-MICROMETER-C7`: RateLimiter 의 두 핵심 metric 명
- **이 자료가 증명하지 않는 것**:
  - Spring Boot starter (`resilience4j-spring-boot3`) 가 자동으로 모든 metric 을 bind 한다는 뜻 — auto-config 동작은 별도 starter 문서 필요
  - Histogram / percentile (p50/p95/p99) 가 default 로 노출된다는 뜻 — Micrometer side 의 `meterFilter` / distributionStatistic 설정 필요할 수 있음
  - Prometheus 의 scrape 주기, retention, alerting rule 의 정확한 형태
  - CircuitBreaker `state` Gauge 의 정확한 라벨 인코딩 (state 별 별도 series 인지 단일 series 의 value 인지)
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - ca-tmpl 의 `resilience4j-spring-boot3` 의존성이 위 metric 들을 `/actuator/prometheus` 에 자동 노출하는지 (`management.endpoints.web.exposure.include=prometheus`)
  - `resilience4j.circuitbreaker.state{state="open"} == 1` 형태의 PromQL 가 작동하는지 (state 인코딩 검증)
  - alerting rule 작성 시 `kind="failed"` label matcher 가 정확히 매치되는지

## 메모 / Notes

- 인용 1 해석 후보 (미검증):
  - state Gauge 의 value 가 boolean(0/1) 인지 enum index 인지는 본 인용에서 미명시 → 실측 필요
- 추가로 봐야 할 동일 출처 페이지:
  - https://resilience4j.readme.io/docs/getting-started-3 (Spring Boot starter auto-config)
  - https://resilience4j.readme.io/docs/circuitbreaker (CircuitBreaker 동작 원리)

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/spring-restclient-builder-reference]] (outbound client 의 baseline)
- 인용하는 branch:
  - [[raw/branch-notes/feature-outbound-http-client-baseline]]
  - [[raw/branch-notes/feature-metrics-alerting-contract]]
- 인용하는 project:
  - [[raw/project-notes/ca-skeleton-operational-contract]]
- 인용하는 wiki: (미작성)