---
title: Spring Framework Observability — ContextPropagatingTaskDecorator 공식 참조
source_type: official-doc
url: https://docs.spring.io/spring-framework/reference/integration/observability.html
archive_url:
related_branches: [feature-background-job-async-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, observability, spring-framework, micrometer]
created: 2026-06-11
---

# Spring Framework Observability — ContextPropagatingTaskDecorator 공식 참조

> Layer: `raw/official-docs/` — Spring Framework 공식 레퍼런스 문서의 원문 발췌·출처 기록.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성.

## Parent / 활용 branch

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-background-job-async-contract]] | D5/D6 — TaskDecorator(ContextPropagatingTaskDecorator)를 setTaskDecorator() 로 등록하는 것이 Spring 공식 권고 패턴이며 Observation context + MDC 가 그 경로로 worker thread 에 전파됨 (span_id explicit MDC copy 불필요 근거) |

## 출처 / Source

- 원본 URL: https://docs.spring.io/spring-framework/reference/integration/observability.html
- 아카이브 URL: (미제공)
- 저자 / 조직: Spring Framework (VMware / Broadcom)
- 발행일: (공식 ref — 버전 지속 갱신)
- 마지막 확인일: 2026-06-11

## 왜 저장했는지 / Why archived

`feature-background-job-async-contract` 의 D5/D6 결정(TaskDecorator 1개로 MDC + Observation context 전파)이 `UNSUPPORTED_DECISION` 으로 표시된 상태를 해소하기 위해 보관. Spring 공식 문서가 `ContextPropagatingTaskDecorator` + `setTaskDecorator()` 패턴을 async context propagation 의 공식 메커니즘으로 기술하며 MDC 전파와 `io.micrometer:context-propagation` 의존성을 명시한다.

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

> [§Global Event Multicaster Configuration / Key Requirements] "The `io.micrometer:context-propagation` library must be present on the classpath"

> [§Global Event Multicaster Configuration / Key Requirements] "Use `setTaskDecorator()` to apply the `ContextPropagatingTaskDecorator`"

> [§Per-Listener Async Configuration / code comment line 88] "// this logging statement will contain the expected MDC entries from the propagated context"

> [§Key Takeaways] "**MDC entries from propagated context** are available in logging statements"

## Claims Extracted / 추출된 주장

> 이 자료가 **직접 말하는 것만** claim 으로 분리한다.

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| SF-OBS-C1 | `ContextPropagatingTaskDecorator` 를 `setTaskDecorator()` 로 TaskExecutor 에 등록하는 것이 Spring 이 권고하는 async context propagation 패턴이다 | [§Key Requirements] "Use `setTaskDecorator()` to apply the `ContextPropagatingTaskDecorator`" | `official-vendor-doc` | Spring Framework + Micrometer Context Propagation 를 사용하는 모든 `@Async` / event listener async 실행 컨텍스트 | 이 패턴이 `ThreadPoolTaskExecutor`(ca-tmpl 사용 클래스) 에서도 동일하게 동작한다는 것은 이 페이지에서 직접 증명하지 않음 — 페이지 예시는 `SimpleAsyncTaskExecutor` 사용 |
| SF-OBS-C2 | async task 실행 시 logging 문 안에서 propagated context 의 MDC 항목이 자동으로 포함된다 | [§code comment] "// this logging statement will contain the expected MDC entries from the propagated context"; [§Benefits] "**MDC entries from propagated context** are available in logging statements" | `official-vendor-doc` | `ContextPropagatingTaskDecorator` 가 설정된 executor 를 통해 실행되는 async task | MDC 에 복사되는 구체적인 키 목록(request_id, trace_id 등)을 이 페이지가 직접 명시하지 않음 |
| SF-OBS-C3 | `io.micrometer:context-propagation` 라이브러리가 classpath 에 존재해야 context propagation 이 동작한다 | [§Key Requirements] "The `io.micrometer:context-propagation` library must be present on the classpath" | `official-vendor-doc` | Spring Framework observability context propagation 전반 | 어느 Spring Boot 버전부터 auto-configured 되는지 이 페이지가 명시하지 않음 |
| SF-OBS-C4 | `ContextPropagatingTaskDecorator` 는 thread boundary 를 가로질러 observability context 를 전파하는 메커니즘이다 | [§Key Takeaways] "**ContextPropagatingTaskDecorator** is the mechanism for propagating observability context across thread boundaries" | `official-vendor-doc` | Micrometer Observation context + MDC propagation across threads | span_id 의 explicit MDC copy 가 *불필요*하다는 것을 이 페이지가 직접 언급하지는 않음 — span_id 는 Observation context 에서 자동 파생된다는 주장은 Micrometer 문서에서 추가 확인 필요 |

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `SF-OBS-C1`: Spring 공식 권고 패턴이 `setTaskDecorator(new ContextPropagatingTaskDecorator())` 임
  - `SF-OBS-C2`: 이 패턴으로 async task 내 logging 에서 MDC entries 가 자동 포함됨
  - `SF-OBS-C3`: `io.micrometer:context-propagation` 의 classpath 의존성이 필수임
  - `SF-OBS-C4`: `ContextPropagatingTaskDecorator` 가 thread boundary 를 가로지르는 observability context propagation 의 공식 메커니즘임
- 이 자료가 증명하지 않는 것:
  - 예시 코드가 `SimpleAsyncTaskExecutor` 를 사용하므로 `ThreadPoolTaskExecutor` 에서의 동일 동작을 이 페이지만으로 보장할 수 없음 (실제로는 동일 인터페이스이나 별도 검증 권고)
  - span_id 의 explicit MDC copy 가 불필요하다는 직접 선언 없음 — Micrometer 문서에서 Observation → MDC span_id 자동 전파 별도 확인 필요
  - 전파되는 MDC 키 목록(request_id / trace_id / correlation_id / tenant_id)을 이 페이지가 열거하지 않음
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-tmpl 의 `ThreadPoolTaskExecutor` bean 에서 `setTaskDecorator(new ContextPropagatingTaskDecorator())` 호출 후 contract test 로 실제 MDC 전파 검증
  - `io.micrometer:context-propagation` 가 ca-tmpl 의 spring-boot 버전에서 자동 포함되는지 또는 명시적 의존성 추가 필요 여부

## 메모 / Notes

- 이 페이지는 `@EventListener` + `@Async` 패턴에 초점을 맞추나, `setTaskDecorator()` API 는 `TaskExecutorConfigurer` / `ThreadPoolTaskExecutor` 에도 동일하게 적용 가능함 (인터페이스 레벨 — 추론, 미검증)
- `SF-OBS-C4` 는 D5 의 "TaskDecorator 1개로 Observation context 전파" 를 뒷받침하나 D6 의 "span_id MDC explicit copy 불필요" 주장은 Micrometer 공식 문서 추가 인용 필요
- 추가로 봐야 할 동일 출처 관련 페이지: `https://docs.micrometer.io/context-propagation/reference/` (context-propagation 라이브러리 레퍼런스)

## Related / 관련

- 같은 주제 다른 official-doc / company-tech-blog: (미작성 — Micrometer context-propagation 공식 레퍼런스 추가 권고)
- 이 자료를 인용한 wiki 요약: (생성 시 추가)