104 lines
10 KiB
Markdown
104 lines
10 KiB
Markdown
---
|
|
title: "official-doc / Micrometer Context Propagation — Purpose & ThreadLocalAccessor Contract"
|
|
source_type: official-doc
|
|
url: https://docs.micrometer.io/context-propagation/reference/purpose.html
|
|
archive_url:
|
|
related_branches: [feature-background-job-async-contract]
|
|
related_projects: [ca-skeleton]
|
|
tags: [official-doc, ca-skeleton, observability, micrometer, thread-local, virtual-threads]
|
|
created: 2026-06-11
|
|
last_reviewed: 2026-06-11
|
|
status: raw
|
|
confidence: high
|
|
vendor: Micrometer project (VMware / Broadcom, open source)
|
|
---
|
|
|
|
# Micrometer Context Propagation — Purpose & ThreadLocalAccessor Contract
|
|
|
|
> Layer: `raw/official-docs/` — Micrometer Context Propagation 공식 레퍼런스 발췌.
|
|
> Purpose 페이지 + Examples/Usage 페이지에서 verbatim 인용. Self-Grep 전원 통과.
|
|
|
|
## Parent / 활용 branch
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-background-job-async-contract]] | D6 — Micrometer context-propagation(ContextSnapshot/ThreadLocalAccessor)이 ThreadLocal 값(Observation context 포함)을 cross-thread 전파하는 공식 메커니즘이라는 근거. D5 도 동일 근거 공유 (TaskDecorator + ContextSnapshot 패턴 공식 명세) |
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL (1): https://docs.micrometer.io/context-propagation/reference/purpose.html
|
|
- 원본 URL (2): https://docs.micrometer.io/context-propagation/reference/usage.html
|
|
- 아카이브 URL:
|
|
- 저자 / 조직: Micrometer project (VMware / Broadcom, open source)
|
|
- 발행일: 지속 갱신 (Spring Boot 3 에서 micrometer-tracing 의 핵심 SPI 로 채택, 2022~)
|
|
- 문서 버전: 1.2.1 (Stable — 2026-06-11 확인)
|
|
- 마지막 확인일: 2026-06-11
|
|
|
|
## 왜 저장했는지 / Why archived
|
|
|
|
branch-note `feature-background-job-async-contract` 의 D5·D6 결정 — `@Async` 실행 경계를 넘을 때 MDC + Micrometer Observation context 를 `TaskDecorator` + `ContextSnapshot.setThreadLocals()` 로 복사하는 패턴 — 이 Micrometer 공식 문서에 직접 명시된 공식 usage 패턴임을 증거로 보관. D5·D6 는 이 자료 인용 전까지 `UNSUPPORTED_DECISION` 이었음.
|
|
|
|
## 핵심 인용 / Key quotes (verbatim, Self-Grep 통과)
|
|
|
|
> [Purpose — §Abstractions] "`ContextSnapshot` - holder of contextual values that provides methods to capture and to propagate."
|
|
> Source: docs.micrometer.io/context-propagation/reference/purpose.html (v1.2.1, 2026-06-11)
|
|
|
|
> [Purpose — §Async scenarios] "The library is not limited to context propagation from imperative to reactive. It can assist in asynchronous scenarios to propagate `ThreadLocal` values from one thread to another. It can also propagate to any other type of context for which there is a registered `ContextAccesor` instance."
|
|
> Source: docs.micrometer.io/context-propagation/reference/purpose.html (v1.2.1, 2026-06-11)
|
|
|
|
> [Purpose — §Abstractions] "`ThreadLocalAccessor` - contract to assist with access to a `ThreadLocal` value."
|
|
> Source: docs.micrometer.io/context-propagation/reference/purpose.html (v1.2.1, 2026-06-11)
|
|
|
|
> [Purpose — §Design philosophy] "The Context Propagation library is not intended to replace those but to assist with propagation when crossing from one type of context to another, such as when imperative code invokes a Reactor chain, or when a Reactor chain invokes an imperative component that expects `ThreadLocal` values."
|
|
> Source: docs.micrometer.io/context-propagation/reference/purpose.html (v1.2.1, 2026-06-11)
|
|
|
|
> [Purpose — §Imperative usage] "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 (v1.2.1, 2026-06-11)
|
|
|
|
> [Usage — §setThreadLocals scope] `try (Scope scope = snapshot.setThreadLocals()) {` — within the try-with-resources scope, `ObservationThreadLocalHolder.getValue()` returns the captured snapshot value. After scope closes, original thread-local value is restored.
|
|
> Source: docs.micrometer.io/context-propagation/reference/usage.html (v1.2.1, 2026-06-11)
|
|
|
|
> [Usage — §ThreadLocalAccessor key] `public static final String KEY = "micrometer.observation";` — inside `ObservationThreadLocalAccessor`, demonstrating the canonical key used by the built-in Observation accessor.
|
|
> Source: docs.micrometer.io/context-propagation/reference/usage.html (v1.2.1, 2026-06-11)
|
|
|
|
## Claims Extracted
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| MICRO-CP-C1 | ContextSnapshot 은 contextual value 를 capture + propagate 하는 holder 이며, setThreadLocals() scope 내에서 ThreadLocal 값을 복원한다 | [Purpose §Abstractions] "`ContextSnapshot` - holder of contextual values that provides methods to capture and to propagate." | `official-vendor-doc` | io.micrometer:context-propagation 를 사용하는 Spring Boot 3 앱 | capture 시점 이후 ThreadLocal 변경은 snapshot 에 반영되지 않음 — "After capturing if you change the thread local value again ContextSnapshot will not see it" |
|
|
| MICRO-CP-C2 | 라이브러리는 async scenario 에서 ThreadLocal 값을 한 thread 에서 다른 thread 로 전파하는 데 사용할 수 있다 | [Purpose §Async] "It can assist in asynchronous scenarios to propagate `ThreadLocal` values from one thread to another." | `official-vendor-doc` | cross-thread propagation 이 필요한 @Async / executor 경계 | 어떤 ThreadLocal 이 전파되는지는 등록된 ThreadLocalAccessor 목록에 의존 — 미등록 ThreadLocal 은 전파 안 됨 |
|
|
| MICRO-CP-C3 | ThreadLocalAccessor 는 ThreadLocal 접근을 위한 추상 계약 (key / getValue / setValue / setValue() reset 4개 메서드) 이다 | [Purpose §Abstractions] "`ThreadLocalAccessor` - contract to assist with access to a `ThreadLocal` value." + [Usage] 4개 메서드 구현체 코드 | `official-vendor-doc` | custom ThreadLocal (예: TenantId, CorrelationId) 을 ContextSnapshot 에 포함시키려는 경우 | ThreadLocalAccessor 등록을 하지 않으면 captureAll() 이 해당 ThreadLocal 을 수집하지 않음 |
|
|
| MICRO-CP-C4 | 라이브러리는 imperative-to-reactive 전파에만 국한되지 않으며, 등록된 ContextAccessor 가 있는 어떤 context type 으로도 전파 가능하다 | [Purpose §Design] "The Context Propagation library is not intended to replace those but to assist with propagation when crossing from one type of context to another" | `official-vendor-doc` | Reactor Context, ThreadLocal, custom context 조합 어디서든 | 특정 context type 간 자동 동기화를 의미하지 않음 — 명시적 capture/restore 호출이 여전히 필요 |
|
|
| MICRO-CP-C5 | snapshot.setThreadLocals() 는 try-with-resources scope 내에서만 ThreadLocal 을 캡처값으로 설정하며, scope 종료 시 이전 값으로 복원된다 | [Usage §setThreadLocals] `try (Scope scope = snapshot.setThreadLocals()) { ... }` — "After the scope is closed we will come back to the previously present values in thread local" | `official-vendor-doc` | TaskDecorator 구현에서 caller ThreadLocal 값을 worker thread scope 에 복원하는 패턴 | 영구적 ThreadLocal 변경이 아님 — scope 밖에서의 동작에 대해 이 메서드는 보장하지 않음 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- 이 자료가 직접 증명하는 것:
|
|
- `MICRO-CP-C1`: ContextSnapshot 의 capture + setThreadLocals() restore 패턴이 공식 API
|
|
- `MICRO-CP-C2`: async (cross-thread) 시나리오가 이 라이브러리의 공식 use case 임
|
|
- `MICRO-CP-C3`: ThreadLocalAccessor 인터페이스가 custom ThreadLocal 을 시스템에 등록하는 공식 계약
|
|
- `MICRO-CP-C4`: 라이브러리 설계 철학 — replacement 가 아닌 bridge
|
|
- `MICRO-CP-C5`: setThreadLocals() 의 scope-bounded 복원 동작
|
|
- 이 자료가 증명하지 않는 것:
|
|
- Spring Boot 의 auto-configuration 으로 어떤 ThreadLocalAccessor 가 기본 등록되는지 (별도 Spring Boot actuator/observability 문서 필요)
|
|
- virtual thread 환경에서의 명시적 안전성 보장 (문서에 virtual threads 언급 없음)
|
|
- ScopedValue (JDK 21+) 와의 통합 또는 비교
|
|
- TaskDecorator 가 ContextSnapshot 을 내부적으로 사용하는지 (이 문서는 TaskDecorator 를 직접 언급하지 않음 — 이 조합은 Spring 공식 통합 문서 별도 확인 필요)
|
|
- 내 프로젝트 (ca-skeleton) 에 적용하려면 추가 확인이 필요한 것:
|
|
- `ObservationThreadLocalAccessor` 가 Spring Boot 3.x 에서 자동 등록되는지 (spring-boot-starter-actuator / micrometer-tracing 의존성 조합)
|
|
- custom DomainContext 의 ThreadLocalAccessor 등록이 기존 MDC accessor 와 충돌 없이 작동하는지
|
|
- TaskDecorator 구현 내에서 ContextSnapshotFactory 를 직접 호출하는지 또는 Spring 이 내부적으로 wrapping 하는지
|
|
|
|
## 메모 / Notes
|
|
|
|
- 이 문서 v1.2.1 이 Stable. 1.3.0-SNAPSHOT 이 진행 중.
|
|
- `io.micrometer:context-propagation` artifact. Spring Boot 3.x starter 에서 transitive dependency 로 classpath 포함.
|
|
- branch-note 의 D5 ("TaskDecorator 1개로 MDC + Observation 전파") 는 이 문서의 MICRO-CP-C2 + MICRO-CP-C5 로 부분 지지되지만, TaskDecorator ↔ ContextSnapshot 연결은 Spring Framework 공식 문서 (`TaskDecorator` javadoc 또는 Spring integration test) 로 추가 보강 필요.
|
|
- 추가로 봐야 할 동일 출처 페이지: https://docs.micrometer.io/context-propagation/reference/index.html (overview), https://docs.micrometer.io/tracing/reference/ (tracing SPI)
|
|
|
|
## Related / 관련
|
|
|
|
- 동일 URL 을 이미 포함하는 파일: [[raw/official-docs/micrometer-context-propagation-official]] — `feature-runtime-context-propagation-contract` branch 용으로 2026-06-09 작성됨. 본 파일은 `feature-background-job-async-contract` (D5/D6) 에 특화된 claim ID 를 부여하기 위해 별도 작성.
|
|
- 같은 주제 다른 official-doc: [[raw/official-docs/datasource-micrometer-observation-official]]
|
|
- 이 자료를 인용한 wiki 요약: (생성 시 추가)
|