llm-wiki/raw/official-docs/tracing-micrometer-observation-introduction.md

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title	source_type	url	archive_url	related_branches	related_projects	tags	created
Micrometer Observation — Introduction (official reference)	official-doc	https://docs.micrometer.io/micrometer/reference/observation/introduction.html		feature-distributed-tracing-contract	ca-skeleton	official-doc ca-skeleton observability micrometer opentelemetry observation-lifecycle	2026-06-14

Micrometer Observation — Introduction (official reference)

Layer: raw/ — 외부 자료(공식 문서 / 대기업 기술 블로그)의 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/에 별도 작성. 원본은 raw에 영구 보관.

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-distributed-tracing-contract	D12 — 예외 발생 시 Observation.error(throwable) 호출 강제: error lifecycle event 가 Observation#error(exception) 호출 시 발생한다는 공식 정의 근거

출처 / Source

• 원본 URL: https://docs.micrometer.io/micrometer/reference/observation/introduction.html
• 아카이브 URL: (미입력)
• 저자 / 조직: Micrometer Authors (VMware / Broadcom)
• 발행일: (정확한 날짜 미기재 — Micrometer 공식 reference 문서)
• 마지막 확인일: 2026-06-14

왜 저장했는지 / Why archived

D12 (span 예외 발생 시 Observation.error(throwable) + error.code 부착)이 UNSUPPORTED_DECISION 이었던 이유는 Micrometer Observation 공식 docs 인용이 없었기 때문이다. 본 자료는 Observation의 error lifecycle event 정의(Observation#error(exception) 호출 시 발생)를 공식 문서에서 verbatim 확보해 D12의 API 계약 측면을 뒷받침한다. TracingObservationHandler와 OTel-side 동작(recordException + setStatus(ERROR))은 이 페이지가 아닌 소스 코드 레벨에서 확인 필요 — 본 자료의 범위 밖임을 메모에 명시한다.

핵심 인용 / Key quotes (verbatim, 3~5문장)

[§Lifecycle events — error] "An error occurred while observing. Happens when the Observation#error(exception) method gets called."

[§Lifecycle events — start] "Observation has been started. Happens when the Observation#start() method gets called."

[§ObservationHandler] "An ObservationHandler reacts only to supported implementations of an Observation.Context and can create timers, spans, and logs by reacting to the lifecycle events of an Observation."

[§Cardinality / Key-Value] "High cardinality means that a pair will have an unbounded number of possible values"

[§Cardinality / Key-Value] "Low cardinality means that a key value will have a bounded number of possible values."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
MICR-OBS-C1	Observation의 error lifecycle event 는 Observation#error(exception) 메서드가 호출될 때 발생한다	[§Lifecycle events — error] "An error occurred while observing. Happens when the Observation#error(exception) method gets called."	official-reference	Micrometer Observation API를 사용하는 모든 코드	error() 호출 시 OTel span에 어떤 attribute가 기록되는지(recordException, setStatus 등)는 이 페이지에서 직접 증명되지 않음
MICR-OBS-C2	Observation의 start lifecycle event 는 Observation#start() 메서드가 호출될 때 발생한다	[§Lifecycle events — start] "Observation has been started. Happens when the Observation#start() method gets called."	official-reference	Micrometer Observation API를 사용하는 모든 코드	start() 호출과 span 시작 시점의 관계는 이 페이지에서 직접 증명되지 않음
MICR-OBS-C3	ObservationHandler는 Observation.Context의 지원되는 구현체에만 반응하며, Observation의 lifecycle event에 반응해 타이머·스팬·로그를 생성할 수 있다	[§ObservationHandler] "An ObservationHandler reacts only to supported implementations of an Observation.Context and can create timers, spans, and logs by reacting to the lifecycle events of an Observation."	official-reference	Micrometer Observation 기반 계측 코드	TracingObservationHandler 가 구체적으로 어떤 OTel API를 호출하는지는 이 페이지에서 증명되지 않음. supportsContext 구현 기준도 별도 확인 필요
MICR-OBS-C4	고카디널리티(High cardinality) key-value 쌍은 값의 범위가 무한대(unbounded)이며, 저카디널리티(Low cardinality) 쌍은 값의 범위가 유한(bounded)이다	[§Cardinality] "High cardinality means that a pair will have an unbounded number of possible values" / "Low cardinality means that a key value will have a bounded number of possible values."	official-reference	Micrometer Observation에서 KeyValue를 설계할 때	특정 attribute(예: error.code)가 고/저 카디널리티 중 어느 쪽인지는 이 페이지에서 직접 말하지 않음

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:

  • MICR-OBS-C1: Observation#error(exception) 호출이 error lifecycle event를 발생시킨다는 API 계약
  • MICR-OBS-C3: ObservationHandler가 lifecycle event에 반응해 span을 포함한 계측 결과물을 생성할 수 있다는 구조적 사실
  • MICR-OBS-C4: High/Low cardinality 구분 기준

• 이 자료가 증명하지 않는 것:

  • Observation.error(throwable) 호출 시 OTel span에 recordException() + setStatus(ERROR)가 실제로 기록되는 것 — 소스 코드(BraveTracingObservationHandler / OtelTracingObservationHandler) 레벨 확인 필요
  • TracingObservationHandler가 supportsContext에서 어떤 컨텍스트를 지원하는지
  • error.code attribute 기록 메커니즘 — OTel Java API 또는 Micrometer Tracing 소스 별도 확인 필요
  • 이 페이지에 "Observation = 단일 API for metrics + traces" 라는 명시적 서술이 있는지 — WebFetch 결과에 해당 직접 표현 없음 (핸들러가 "timers, spans, logs"를 생성할 수 있다는 서술이 간접적 근거)

• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:

  • OtelTracingObservationHandler.onError() 소스를 직접 읽어 recordException 호출 여부 확인
  • error.code attribute 부착이 Micrometer Observation 내에서 자동인지 수동(Convention 설정)인지 확인

메모 / Notes

• OTel-side 동작은 이 페이지 범위 밖: Observation.error(throwable) 호출 시 span에 recordException() + setStatus(ERROR)가 기록된다는 것은 OtelTracingObservationHandler 소스 코드 레벨 사실이며, 본 introduction 페이지에서는 직접 확인되지 않음. D12의 error.code attribute 자동 부착 메커니즘도 동일하게 소스 레벨 또는 Micrometer Tracing reference 별도 fetch 필요.
• 추가로 봐야 할 동일 출처 페이지: https://docs.micrometer.io/micrometer/reference/observation/handler.html (ObservationHandler 상세), https://docs.micrometer.io/tracing/reference/index.html (Micrometer Tracing — TracingObservationHandler 상세)

Related / 관련

• 같은 주제 다른 official-doc: raw/official-docs/tracing-w3c-trace-context-spec.md, raw/official-docs/tracing-otel-sampling-tail-vs-head-spec.md
• 이 자료를 인용한 wiki 요약: (생성 시 추가)