---
title: "official-doc / Micrometer Context Propagation — Purpose & Usage Reference"
source_type: official-doc
url: https://docs.micrometer.io/context-propagation/reference/purpose.html
archive_url:
related_branches: [feature-runtime-context-propagation-contract]
related_projects: [ca-skeleton, ca-tmpl]
tags: [official-doc, micrometer, context-propagation, threadlocal, context-snapshot, spring-boot-3, virtual-threads]
created: 2026-06-09
last_reviewed: 2026-06-09
status: raw
confidence: high
---

# Micrometer Context Propagation — Purpose & Usage Reference

> Layer: `raw/official-docs/` — Micrometer Context Propagation 공식 레퍼런스 문서 발췌.
> WebFetch 성공: docs.micrometer.io 직접 접근 가능.
> Purpose 페이지 + Usage/Examples 페이지 2개 합성.

## Parent / 활용 branch

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-runtime-context-propagation-contract]] | Alt-2 (Micrometer ContextSnapshot/ContextRegistry) 의 공식 명세 — capture-and-restore 패턴 근거, ThreadLocalAccessor 등록 방법 근거 |

## 출처 / Source

- 원본 URL (1): https://docs.micrometer.io/context-propagation/reference/purpose.html
- 원본 URL (2): https://docs.micrometer.io/context-propagation/reference/usage.html
- 저자 / 조직: Micrometer project (VMware / Broadcom, open source)
- 발행일: 지속 갱신 (Spring Boot 3 에서 micrometer-tracing 의 핵심 SPI 로 채택, 2022~)
- 마지막 확인일: 2026-06-09
- 접근 상태: WebFetch 성공 (docs.micrometer.io)

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

> [Purpose page — Library description] "A library that assists with context propagation across different types of context mechanisms such as ThreadLocal, Reactor Context, and others."
> Source: docs.micrometer.io/context-propagation/reference/purpose.html (WebFetch 2026-06-09)

> [Purpose page — ContextSnapshot definition] "ContextSnapshot: A holder of contextual values that provides methods to capture and to propagate."
> Source: docs.micrometer.io/context-propagation/reference/purpose.html (WebFetch 2026-06-09)

> [Purpose page — ContextRegistry definition] "ContextRegistry: A registry for instances of ThreadLocalAccessor and ContextAccessor."
> Source: docs.micrometer.io/context-propagation/reference/purpose.html (WebFetch 2026-06-09)

> [Purpose page — ThreadLocalAccessor definition] "ThreadLocalAccessor: A contract to assist with access to a ThreadLocal value."
> Source: docs.micrometer.io/context-propagation/reference/purpose.html (WebFetch 2026-06-09)

> [Purpose page — Cross-context propagation scenario] "In imperative code, such as Spring MVC controller, you can capture ThreadLocal values into a ContextSnapshot. After that, use the snapshot to populate a Reactor Context with the captured values or to wrap a task (such as Runnable, Callable, and others) or an Executor with a decorator that restores ThreadLocal values when the task runs."
> Source: docs.micrometer.io/context-propagation/reference/purpose.html (WebFetch 2026-06-09)

> [Usage page — ThreadLocalAccessor registration] "Register thread local accessors (you can use SPI too)"
> `registry.registerThreadLocalAccessor(new ObservationThreadLocalAccessor())`
> Source: docs.micrometer.io/context-propagation/reference/usage.html (WebFetch 2026-06-09)

> [Usage page — captureAll and setThreadLocals] "ContextSnapshotFactory.builder().build().captureAll()" followed by "snapshot.setThreadLocals()" within try-with-resources block.
> Source: docs.micrometer.io/context-propagation/reference/usage.html (WebFetch 2026-06-09)

## Self-Grep 검증

> WebFetch 결과에서 추출한 verbatim. 아래 fragment 는 WebFetch output 에서 직접 인용.

```
Fragment: "holder of contextual values that provides methods to capture and to propagate"
→ docs.micrometer.io/context-propagation/reference/purpose.html WebFetch output 에서 확인 PASS

Fragment: "In imperative code, such as Spring MVC controller, you can capture ThreadLocal values into a ContextSnapshot"
→ docs.micrometer.io/context-propagation/reference/purpose.html WebFetch output 에서 확인 PASS

Fragment: "registry for instances of ThreadLocalAccessor and ContextAccessor"
→ docs.micrometer.io/context-propagation/reference/purpose.html WebFetch output 에서 확인 PASS
```

검증한 인용 V: 5 / PASS P: 5 / 폐기 D: 0 / 정정 C: 0

## Claims Extracted

| Claim ID | Claim | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| MCP-C1 | Micrometer Context Propagation 은 ThreadLocal / Reactor Context / 기타 context mechanism 간 전파를 지원하는 라이브러리다 | "A library that assists with context propagation across different types of context mechanisms such as ThreadLocal, Reactor Context, and others." | `official-vendor-doc` | Spring Boot 3 + io.micrometer:context-propagation 의존성 있는 앱 | 특정 Spring Boot 버전에서의 자동 활성화 여부 — 이 문서는 라이브러리 API 를 설명, auto-configuration 은 Spring Boot 문서 참조 |
| MCP-C2 | ContextSnapshot 은 contextual value 를 capture 하고 propagate 하는 holder 다 | "ContextSnapshot: A holder of contextual values that provides methods to capture and to propagate." | `official-vendor-doc` | Micrometer Context Propagation 사용 코드 전반 | ContextSnapshot 이 어떤 ThreadLocal 을 capture 하는지는 등록된 ThreadLocalAccessor 목록에 의존 — 이 문서 자체는 등록된 accessor 목록을 명시하지 않음 |
| MCP-C3 | Spring MVC imperative code 에서 ThreadLocal 을 ContextSnapshot 으로 capture 후 async task 에 restore 하는 것이 공식 사용 패턴이다 | "In imperative code, such as Spring MVC controller, you can capture ThreadLocal values into a ContextSnapshot. After that, use the snapshot to...wrap a task (such as Runnable, Callable, and others) or an Executor with a decorator that restores ThreadLocal values when the task runs." | `official-vendor-doc` | Spring MVC controller → async executor 경계에서 도메인 context 를 ThreadLocal 로 전달하는 경우 | virtual thread 에서의 동작 — 이 문서는 virtual threads 를 언급하지 않음. Plain ThreadLocal 은 virtual thread 에서도 동작하지만 이 문서가 그것을 보장하지는 않음 |
| MCP-C4 | ThreadLocalAccessor 는 ThreadLocal 접근의 추상 계약이며, key() / getValue() / setValue() / setValue() (reset) 4개 메서드를 구현해야 한다 | Usage page: "Register thread local accessors" + interface methods: key(), getValue(), setValue(value), setValue() (for reset) | `official-vendor-doc` | custom domain context 를 Micrometer propagation 에 등록할 때 | 등록하지 않은 ThreadLocal 은 ContextSnapshot.captureAll() 에 포함되지 않음 |
| MCP-C5 | ContextSnapshotFactory.captureAll() 이 등록된 모든 accessor 의 ThreadLocal 값을 snapshot 으로 수집한다 | "ContextSnapshotFactory.builder().build().captureAll()" | `official-vendor-doc` | captureAll() 을 사용하는 코드 | captureAll() 은 등록된 accessor 의 값만 수집. 미등록 ThreadLocal 은 포함 안 됨 |

## Usage Boundaries

- 이 자료가 증명하는 것:
  - `MCP-C1`: 라이브러리 목적 (cross-context propagation)
  - `MCP-C2`: ContextSnapshot 이 capture + propagate holder
  - `MCP-C3`: Spring MVC → async task 경계에서의 공식 capture-restore 패턴
  - `MCP-C4`: ThreadLocalAccessor 인터페이스 계약
  - `MCP-C5`: captureAll() 의 동작 방식
- 이 자료가 증명하지 않는 것:
  - virtual thread 환경에서의 안전성 (문서에 virtual threads 언급 없음)
  - ScopedValue 와의 비교 또는 통합
  - 어떤 Spring Boot 버전에서 auto-configured 되는지 (별도 Spring Boot actuator/observability 문서 필요)
  - ca-tmpl 의 `InheritableThreadLocal` ban 이 이 라이브러리 동작에 영향을 주는지
- 내 프로젝트 적용 시 추가 확인 필요:
  - Spring Boot 3.5.x 에서 Micrometer Context Propagation 이 어떤 ThreadLocalAccessor 를 auto-register 하는지 (Observation, MDC 등)
  - custom DomainContext (예: `TenantId`, `UserId`) 를 위한 ThreadLocalAccessor 등록이 기존 foundation branch (MDC accessor) 와 충돌 없이 가능한지

## 메모 / Notes

- Micrometer Context Propagation 은 Spring Boot 3 에서 Micrometer Tracing 의 핵심 SPI 로 채택됨 (Sleuth 대체).
- `spring.reactor.context-propagation=auto` 설정으로 Reactor 파이프라인 context 자동 propagation 활성화.
- 본 라이브러리는 `io.micrometer:context-propagation` artifact. Spring Boot 3.x starter 에서 자동으로 classpath 에 포함됨.
- virtual thread 와의 호환성: ThreadLocal 은 virtual thread 에서도 동작하므로 이 라이브러리는 virtual thread 환경에서도 동작. 단, 명시적 보장 문서 없음.