Files
clean-architecture-backend-…/docs/registries/mdc-keys.yaml
T
DongHyeonka 354b7fc959
pr / done (pull_request) Canceled after 0s
fix(observability)!: 지표·MDC·헤더 registry를 코드가 실제로 내는 것과 맞춘다
관측 registry가 코드와 양쪽으로 어긋난다. metrics.yaml에는 아무 코드도
등록하지 않는 행 열하나와 코드에 없는 tag 값이 있고, 코드가 등록하는
graphql·notification·http.client·fileserver·mongodb·jpa.query 지표 다수가
없다. mdc-keys.yaml은 18키 중 코드가 넣는 5키만 맞고 required_in이 틀렸다.
headers.yaml은 X-Request-Id·X-Correlation-Id를 ulid로 적고 아무도 쓰지
않는 Deprecation·Sunset·tracestate를 적는다. 전송마다 correlation 규칙이
다른데 registry는 하나로 적는다. 단일 인스턴스 in-process lock은
lock.acquisition을 세지 않아 그 지표가 0이다. 밑줄 든 meter 이름 둘이
이름 규칙을 어긴다.

- 행마다 등록하는 main 파일(source)·상수(constant)·등록 주체
  (registered_by)를 적고, MetricsRegistryCodeAlignmentTest가 행 → 코드(이름이
  상수면 그 상수를 쓰는 곳까지)와 코드(글자·상수 이름의 builder·registry·
  Metrics 호출) → 행 두 방향을 본다. 템플릿이 부르지 않는 공개 메서드로만
  생기는 job.* 행은 emitted_when을 적는다. 버린 안: 행만 지우기(새 지표가
  다시 빠진다).
- mdc-keys는 5키와 전송별 표, headers는 source가 든 33행(서비스 controller용
  상수는 service: 출처), StructuredLog·HeaderRegistry 시험이 코드 상수와
  집합을 대조한다. 두 registry 시험은 시험 도우미 MainSources를 같이 쓴다.
- slo_driven 행은 MetricsDistributionMeterFilter 대상과 같은 집합이다(두
  방향 시험). histogram을 켜지 않는 hikaricp timer 행은 평균으로 경보한다.
  graphql.datafetcher·dataloader 행에 Spring 기본 tag를 적는다.
- in-process lock을 MeteredDistributedLock으로 감싼다.
- http.client.ratelimit.rejected, fileserver.upload.offset.mismatch로
  이름을 바꾸고 http.client.circuit.state.rejected를 상수로 둔다.
- CardinalityBounds(status 40·outcome 6·uri), MetricNaming 단위 규칙,
  SLO filter 대상(http.server.requests·jvm.gc.pause)을 문서와 맞춘다.

위험: 지표 이름 둘이 바뀌고 단일 인스턴스 lock 지표가 생긴다. 그 이름으로
만든 대시보드·경보를 옮겨야 한다(docs/upgrade/2026-11-round9-observability.md
8~13행). ApachePoolMetricsBinder·MongoTransactionRetry 지연은 다른 묶음이
맡는다.

검증: 위와 같은 desktop 실행(묶음 셋을 합친 트리) rc=0.

Refs: RR9-02-05, RR9-02-07, RR9-02-08, RR9-02-27, RR9-03-05
BREAKING CHANGE: http.client.rate_limit.rejected → http.client.ratelimit.rejected,
  fileserver.upload.offset_mismatch → fileserver.upload.offset.mismatch,
  CardinalityBounds 상수. docs/upgrade/2026-11-round9-observability.md 8~13행.
2026-11-13 13:12:27 +09:00

104 lines
5.1 KiB
YAML

# Registry: MDC / Log Keys
# Schema owner: feature-contract-registry-governance
# MDC SSOT: feature-operational-error-observability-foundation
# Last updated: 2026-11-13
#
# 표기 규칙
# - MDC key 이름: snake_case (foundation L93 "snake_case 강제. camelCase / dot.case 금지.")
# - cardinality_safe_for_metric=true 인 key만 metric tag로 사용 가능
# - 행은 코드가 실제로 MDC에 넣는 key다. 코드의 정본은 `MdcKeys`(shared-contract)이고, 이 파일의 key 집합과
# `MdcKeys` 상수 집합이 같은지 `StructuredLogFieldContractTest`가 본다. `written_by`가 넣는 곳이다.
# - 구조화 로그 칸(`error.code`, `capability`, `operation`, `warning.kind` 등, dot.case 포함)은 MDC key가 아니라
# logstash `kv(...)` 인자다. 그 칸의 정본은 `docs/observability/log-fields.md`다. method·status·duration_ms·uri_template은
# 요청 로그 줄의 메시지 글자다(`RequestLoggingFilter`).
#
# 전송마다 넣는 key (전송마다 다르다. 같게 맞추지 않고 여기 적는다)
# | 전송 | request_id | correlation_id | trace_id·span_id |
# | --- | --- | --- | --- |
# | web(`WebMvcRequestIdFilter`) | 새 UUID. `app.web.mvc.trust-inbound-request-id=true`일 때만 caller의 `X-Request-Id`(`[A-Za-z0-9._-]{1,128}`) | caller의 `X-Correlation-Id`(같은 문법), 없거나 틀리면 새 UUID | 활성 span, 없으면 caller `traceparent`, 없으면 새로 만든다 |
# | gRPC(`GrpcCorrelationInterceptor`) | 호출마다 새 UUID(caller 값을 받지 않는다) | 넣지 않는다(연결·세션 개념이 없다) | 유효한 `traceparent` metadata가 있을 때만 |
# | STOMP(`WebSocketCorrelationInterceptor`) | frame마다 새 UUID | STOMP session id(한 연결의 frame을 잇는다) | 넣지 않는다 |
# | GraphQL(HTTP) | web filter가 넣은 값을 그대로 쓴다 | 같음 | 같음 |
# - user_principal은 web 요청 로그 줄을 쓰는 동안만 있다(HMAC 가명). 비동기 작업은 `AsyncContextTaskDecorator`가
# 호출한 쪽 MDC 전체를 옮긴다.
mdc_keys:
# source: feature-operational-error-observability-foundation.md L97
- key: request_id
type: uuid-or-caller-token
format: "UUID; web은 trust-inbound-request-id=true일 때 [A-Za-z0-9._-]{1,128}"
source: inbound_filter
written_by: [WebMvcRequestIdFilter, GrpcCorrelationInterceptor, WebSocketCorrelationInterceptor]
required_in: [request, dependency, security, application]
http_header_mapping: X-Request-Id
envelope_field: meta.requestId
propagation: [http, async]
owner_branch: feature-operational-error-observability-foundation
cardinality_safe_for_metric: false
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-mdc-keys
# source: feature-operational-error-observability-foundation.md L98
- key: trace_id
type: string
format: "W3C trace-id, 32 lowercase hex"
source: observation_context
written_by: [WebMvcRequestIdFilter, GrpcCorrelationInterceptor]
required_in: [request, dependency, application]
http_header_mapping: traceparent
envelope_field: meta.traceId
propagation: [http, async]
owner_branch: feature-operational-error-observability-foundation
cardinality_safe_for_metric: false
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-mdc-keys
- key: span_id
type: string
format: "W3C parent-id, 16 lowercase hex"
source: observation_context
written_by: [WebMvcRequestIdFilter, GrpcCorrelationInterceptor]
required_in: [request, dependency]
http_header_mapping: traceparent
envelope_field: null
propagation: [http, async]
owner_branch: feature-operational-error-observability-foundation
cardinality_safe_for_metric: false
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-mdc-keys
# source: feature-operational-error-observability-foundation.md L100
- key: correlation_id
type: uuid-or-caller-token
format: "web: caller X-Correlation-Id [A-Za-z0-9._-]{1,128} 또는 UUID; STOMP: session id"
source: inbound_filter
written_by: [WebMvcRequestIdFilter, WebSocketCorrelationInterceptor]
required_in: [request, dependency, application]
http_header_mapping: X-Correlation-Id
envelope_field: meta.correlationId
propagation: [http, async, message]
owner_branch: feature-operational-error-observability-foundation
cardinality_safe_for_metric: false
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-mdc-keys
# source: feature-operational-error-observability-foundation.md L102
- key: user_principal
type: string
format: "HMAC 가명(PrivacySettings)"
source: security_context
written_by: [RequestLoggingFilter]
required_in: [security, audit]
http_header_mapping: null
envelope_field: null
propagation: [none]
owner_branch: feature-operational-error-observability-foundation
cardinality_safe_for_metric: false
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-mdc-keys