# 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