96 lines
8.9 KiB
Markdown
96 lines
8.9 KiB
Markdown
---
|
|
title: "Spring Boot Actuator Tracing Reference — Micrometer Tracing, OpenTelemetry, Brave"
|
|
source_type: official-doc
|
|
url: https://docs.spring.io/spring-boot/reference/actuator/tracing.html
|
|
archive_url:
|
|
related_branches: [feature-distributed-tracing-contract]
|
|
related_projects: [ca-skeleton]
|
|
tags: [official-doc, ca-skeleton, tracing, observability, micrometer, opentelemetry, spring-boot]
|
|
created: 2026-06-14
|
|
---
|
|
|
|
# Spring Boot Actuator Tracing Reference — Micrometer Tracing, OpenTelemetry, Brave
|
|
|
|
> Layer: `raw/official-docs/` — Spring Boot 공식 reference 문서에서 발췌한 원본 인용 + 출처 기록.
|
|
> 검증된 요약은 `/ingest` 후 `wiki/concepts/` 에 별도 작성. 원본은 raw 에 영구 보관.
|
|
|
|
## Parent / 활용 branch
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-distributed-tracing-contract]] | D1 — Micrometer Tracing + OpenTelemetry exporter 기본 채택 (Spring Boot Actuator 가 Micrometer Tracing 을 auto-configure 하고, OTel+OTLP 와 Brave+Zipkin 두 tracer 를 공식 지원함 — vendor-neutral OTLP + W3C traceparent default 의 근거) |
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://docs.spring.io/spring-boot/reference/actuator/tracing.html
|
|
- 아카이브 URL: (미등록)
|
|
- 저자 / 조직: Pivotal / VMware (Spring team)
|
|
- 발행일: Spring Boot 4.1.x reference (현행 최신 stable — 2026-06-14 기준 live)
|
|
- 마지막 확인일: 2026-06-14
|
|
|
|
## 왜 저장했는지 / Why archived
|
|
|
|
`feature-distributed-tracing-contract` 의 D1 결정 ("Micrometer Tracing + OpenTelemetry exporter 기본 채택") 이 `UNSUPPORTED_DECISION` 으로 표시되어 있었다. 본 공식 문서는 Spring Boot Actuator 가 Micrometer Tracing 을 facade 로 auto-configure 하며, OTel+OTLP 와 Brave+Zipkin 두 tracer 모두 공식 지원(각 dedicated starter 존재)함을 직접 명시한다. 이로써 "vendor-neutral OTLP 채택" 의 공식 근거를 확보한다.
|
|
|
|
**중요 framing**: 이 문서는 OTel 이 "유일한 default" 임을 주장하지 않는다. Spring Boot 는 OTel+OTLP 와 Brave+Zipkin **양쪽 모두** 를 공식 지원한다. D1 의 정당화는 "OTel 만 지원" 이 아니라 "OTel+OTLP 를 채택하면 vendor-neutral W3C traceparent 와 OTLP export 가 Spring Boot 공식 auto-config 범위 안에 있다" 는 것이다.
|
|
|
|
## 핵심 인용 / Key quotes (verbatim, 5개)
|
|
|
|
> [§intro] "Spring Boot Actuator provides dependency management and auto-configuration for Micrometer Tracing, a facade for popular tracer libraries."
|
|
|
|
> [§Supported Tracers] "Spring Boot ships auto-configuration for the following tracers:"
|
|
> — 이 문장 바로 아래 두 bullet:
|
|
> "* OpenTelemetry with OTLP."
|
|
> "* OpenZipkin Brave with Zipkin."
|
|
|
|
> [§Tracer Implementations] "As Micrometer Tracer supports multiple tracer implementations, there are multiple dependency combinations possible with Spring Boot. The combinations OpenTelemetry with OTLP and Brave with Zipkin are common and have dedicated starters."
|
|
|
|
> [§OpenTelemetry With OTLP] "Tracing with OpenTelemetry and reporting using OTLP requires the following dependencies:"
|
|
> — bullet: "* org.springframework.boot:spring-boot-starter-opentelemetry"
|
|
|
|
> [§Baggage] "The baggage is automatically propagated over the network if you're using W3C propagation. If you're using B3 propagation, baggage is not automatically propagated."
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| SB-TRAC-C1 | Spring Boot Actuator 는 Micrometer Tracing(인기 있는 tracer library 의 facade)에 대한 dependency management 와 auto-configuration 을 제공한다 | [§intro] "Spring Boot Actuator provides dependency management and auto-configuration for Micrometer Tracing, a facade for popular tracer libraries." | `official-vendor-doc` | Spring Boot Actuator 를 사용하는 모든 Spring Boot 3+ 애플리케이션 | Micrometer Tracing 이 "기본으로 활성화" 된다는 뜻은 아님 — starter 의존성 추가가 여전히 필요 |
|
|
| SB-TRAC-C2 | Spring Boot 는 OTel+OTLP 와 OpenZipkin Brave+Zipkin **두 가지** tracer 에 대해 auto-configuration 을 제공한다 | [§Supported Tracers] "Spring Boot ships auto-configuration for the following tracers: * OpenTelemetry with OTLP. * OpenZipkin Brave with Zipkin." | `official-vendor-doc` | Spring Boot 공식 tracer 목록 | OTel 이 "유일한" 또는 "기본" tracer 임을 증명하지 않음 — 둘 다 동등하게 공식 지원 |
|
|
| SB-TRAC-C3 | OTel+OTLP 와 Brave+Zipkin 두 조합은 common 하며 각각 dedicated starter 가 존재한다 | [§Tracer Implementations] "The combinations OpenTelemetry with OTLP and Brave with Zipkin are common and have dedicated starters." | `official-vendor-doc` | Spring Boot 애플리케이션에서 tracer 의존성 선택 | "common" 은 Spring 팀의 용례 관찰이지, 프로젝트가 반드시 둘 중 하나를 선택해야 한다는 강제 아님 |
|
|
| SB-TRAC-C4 | OTel+OTLP tracing 을 위한 공식 starter 는 `org.springframework.boot:spring-boot-starter-opentelemetry` 이다 | [§OpenTelemetry With OTLP] "Tracing with OpenTelemetry and reporting using OTLP requires the following dependencies: * org.springframework.boot:spring-boot-starter-opentelemetry" | `official-vendor-doc` | OTel+OTLP 를 선택한 Spring Boot 애플리케이션 | starter 추가만으로 tracing 이 완전히 동작한다는 뜻 아님 — OTLP endpoint 설정(`management.opentelemetry.tracing.export.otlp.*`) 추가 필요 |
|
|
| SB-TRAC-C5 | W3C propagation 사용 시 baggage 가 네트워크 전체에 자동 전파되나, B3 propagation 사용 시 baggage 는 자동 전파되지 않는다 | [§Baggage] "The baggage is automatically propagated over the network if you're using W3C propagation. If you're using B3 propagation, baggage is not automatically propagated." | `official-vendor-doc` | Spring Boot Micrometer Tracing 의 baggage propagation 동작 | B3 를 사용하면서도 baggage 를 전파하는 방법(수동 `management.tracing.baggage.remote-fields` 설정)에 대한 별도 판단은 이 인용만으로 불충분 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- 이 자료가 직접 증명하는 것:
|
|
- `SB-TRAC-C1`: Spring Boot Actuator 가 Micrometer Tracing 을 auto-configure 한다 — D1 의 "Spring Boot 공식 지원" 근거
|
|
- `SB-TRAC-C2`: OTel+OTLP 와 Brave+Zipkin 두 tracer 모두 Spring Boot 공식 auto-config 대상이다
|
|
- `SB-TRAC-C3`: 두 조합 모두 dedicated starter 가 있으며 common use case 이다
|
|
- `SB-TRAC-C4`: `spring-boot-starter-opentelemetry` 가 OTel+OTLP 를 위한 공식 starter 이다
|
|
- `SB-TRAC-C5`: W3C propagation 시 baggage 자동 전파, B3 시 수동 설정 필요
|
|
- 이 자료가 증명하지 않는 것:
|
|
- OTel 이 Spring Boot 의 "기본(default)" tracer 라는 것 — Spring Boot 는 둘 다 지원하며 하나를 default 로 지정하지 않는다
|
|
- Micrometer Tracing 이 의존성 추가 없이 자동 활성화된다는 것 — starter 의존성 필요
|
|
- prod 환경에서의 sampling rate 권장값 (prod 1%, staging 10% 등 ca-tmpl 정책은 이 문서의 근거 아님)
|
|
- force-sample 메커니즘의 구현 방법 (error/slow/retry-exhausted 시 force-sample 은 별도 SDK 구현)
|
|
- Micrometer Tracing TaskDecorator 의 @Async 경계 자동 전파 여부
|
|
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
|
- ca-tmpl 이 실제로 `spring-boot-starter-opentelemetry` 를 사용하는지 (`workspace/ca-tmpl` build.gradle / pom.xml 확인 필요)
|
|
- OTLP endpoint 설정(`management.opentelemetry.tracing.export.otlp.*`) 이 ca-tmpl 설정 파일에 존재하는지
|
|
- W3C propagation 이 ca-tmpl 의 default 설정인지, 별도 설정(`management.tracing.propagation.*`)이 필요한지
|
|
|
|
## 메모 / Notes
|
|
|
|
- 이 페이지는 Spring Boot 4.1.x reference 기준. Spring Boot 3.x 의 reference URL 구조가 달라 이 URL 은 최신 버전을 가리킬 수 있음 — version-specific URL 로 고정이 필요하면 archive 등록 권고.
|
|
- `§OpenTelemetry With Zipkin` 섹션에서 "OpenTelemetry has deprecated their Zipkin support. The auto-configuration for it will be removed in Spring Boot 4.2." 가 명시됨 — OTel+Zipkin 조합은 deprecated, Brave+Zipkin 또는 OTel+OTLP 로 이전 권장.
|
|
- `SB-TRAC-C2` 는 D1 의 "Micrometer Tracing + OpenTelemetry exporter 기본 채택" 을 `UNSUPPORTED_DECISION` 에서 `official-vendor-doc` 근거로 올려주되, "OTel 이 유일" 이 아니라 "두 tracer 중 OTel+OTLP 를 선택" 임을 명확히 framing 해야 함.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc / company-tech-blog:
|
|
- [[raw/official-docs/tracing-w3c-trace-context-spec]]
|
|
- [[raw/official-docs/tracing-otel-sampling-tail-vs-head-spec]]
|
|
- [[raw/official-docs/tracing-b3-propagation-zipkin-spec]]
|
|
- [[raw/company-tech-blogs/tracing-datadog-apm-vs-opentelemetry]]
|
|
- 이 자료를 인용한 wiki 요약: (미생성 — `/ingest` 후 `wiki/concepts/` 에 작성 예정)
|