pr / done (pull_request) Canceled after 0s
관측 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행.
104 lines
5.1 KiB
YAML
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
|