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

---
title: "Micrometer Observation — Introduction (official reference)"
source_type: official-doc
url: https://docs.micrometer.io/micrometer/reference/observation/introduction.html
archive_url:
related_branches: [feature-distributed-tracing-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, observability, micrometer, opentelemetry, observation-lifecycle]
created: 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 요약: (생성 시 추가)