Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

10 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, related_branches, related_projects, tags, created, last_reviewed, status, confidence, vendor

title

source_type

url

archive_url

related_branches

related_projects

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)

동일 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 요약: (생성 시 추가)

10 KiB Raw Permalink Blame History