clean-architecture-backend-template/docs/registries/mdc-keys.yaml

# Registry: MDC / Log Keys
# SSOT: wiki/projects/ca-tmpl/registries/mdc-keys.yaml
# Schema owner: feature-contract-registry-governance
# MDC SSOT: feature-operational-error-observability-foundation
# Last updated: 2026-05-22
#
# Conventions:
# - MDC key naming: snake_case (foundation L93 "snake_case 강제. camelCase / dot.case 금지.")
# - cardinality_safe_for_metric=true 인 key만 metric tag로 사용 가능
# - foundation L93-102 표 "MDC Key Standard (final)" 6개가 core SSOT

mdc_keys:
  # source: feature-operational-error-observability-foundation.md L97
  #   "request_id | inbound filter (생성 또는 X-Request-Id 헤더) | response header X-Request-Id"
  - key: request_id
    type: ulid
    source: inbound_filter
    required_in: [request, dependency, security, application]
    http_header_mapping: X-Request-Id
    envelope_field: meta.requestId
    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 L98
  #   "trace_id | Micrometer Tracing | W3C traceparent header"
  - key: trace_id
    type: string
    source: observation_context
    required_in: [request, dependency, application]
    http_header_mapping: traceparent
    envelope_field: meta.traceId
    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 L99
  #   "span_id | Micrometer Tracing | W3C traceparent"
  # NOTE: background-job-async-contract L71 "span_id는 Micrometer Observation context에서 자동 전파(MDC explicit copy 불필요)"
  - key: span_id
    type: string
    source: observation_context
    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
  #   "correlation_id | inbound header X-Correlation-Id 또는 생성 | HTTP X-Correlation-Id, message header correlation_id"
  - key: correlation_id
    type: ulid
    source: inbound_filter
    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 L101 + feature-tenant-context-policy.md L70
  #   "tenant_id | tenant context (활성 시) | downstream HTTP X-Tenant-Id (with allowlist)" /
  #   "tenant ID format = opaque ULID (26 chars Crockford base32)"
  # NOTE: tenant L73 "tenant_id ULID 원본은 metric tag에 직접 사용 금지"
  - key: tenant_id
    type: ulid
    source: security_context
    required_in: [request, dependency, security, audit]
    http_header_mapping: X-Tenant-Id
    envelope_field: null
    propagation: [http, async, message]
    owner_branch: feature-tenant-context-policy
    cardinality_safe_for_metric: false
    case_style: snake
    compatibility_impact: additive
    required_test: contract-verification:tenant-leakage

  # source: feature-operational-error-observability-foundation.md L102
  #   "user_principal | security context (pseudonymized only) | log only, headers forbidden"
  - key: user_principal
    type: string
    source: security_context
    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

  # ── log type extensions (log-management-contract L101-109 "Log Type별 필수 필드") ──

  # source: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms"
  # NOTE: application-port-usecase-contract / business 측 operation 식별자 (uri_template과 별도 application-set)
  - key: operation
    type: string
    source: application_set
    required_in: [application, dependency]
    http_header_mapping: null
    envelope_field: null
    propagation: [none]
    owner_branch: feature-log-management-contract
    cardinality_safe_for_metric: true
    case_style: snake
    compatibility_impact: none
    required_test: contract-verification:log-fields

  # source: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms"
  - key: method
    type: string
    source: inbound_filter
    required_in: [request]
    http_header_mapping: null
    envelope_field: null
    propagation: [none]
    owner_branch: feature-log-management-contract
    cardinality_safe_for_metric: true
    case_style: snake
    compatibility_impact: none
    required_test: contract-verification:log-fields

  # source: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms"
  # NOTE: metrics L86 "status_code | 7 (1xx-5xx + ok/other)" — bounded
  - key: status
    type: numeric
    source: inbound_filter
    required_in: [request]
    http_header_mapping: null
    envelope_field: null
    propagation: [none]
    owner_branch: feature-log-management-contract
    cardinality_safe_for_metric: true
    case_style: snake
    compatibility_impact: none
    required_test: contract-verification:log-fields

  # source: feature-log-management-contract.md L105-106 "request | ... duration_ms" / "dependency | ... duration_ms"
  - key: duration_ms
    type: numeric
    source: application_set
    required_in: [request, dependency]
    http_header_mapping: null
    envelope_field: null
    propagation: [none]
    owner_branch: feature-log-management-contract
    cardinality_safe_for_metric: false
    case_style: snake
    compatibility_impact: none
    required_test: contract-verification:log-fields

  # source: feature-log-management-contract.md L106 "dependency | dependency_name, dependency_type, duration_ms, outcome, error_code"
  # NOTE: metrics L88 "dependency_name | 50" — bounded
  - key: dependency_name
    type: string
    source: application_set
    required_in: [dependency]
    http_header_mapping: null
    envelope_field: null
    propagation: [none]
    owner_branch: feature-log-management-contract
    cardinality_safe_for_metric: true
    case_style: snake
    compatibility_impact: none
    required_test: contract-verification:log-fields

  # source: feature-log-management-contract.md L106 "dependency | dependency_name, dependency_type, ..."
  - key: dependency_type
    type: string
    source: application_set
    required_in: [dependency]
    http_header_mapping: null
    envelope_field: null
    propagation: [none]
    owner_branch: feature-log-management-contract
    cardinality_safe_for_metric: true
    case_style: snake
    compatibility_impact: none
    required_test: contract-verification:log-fields

  # source: feature-log-management-contract.md L106 + metrics L91 "outcome (resilience4j) | 5 (SUCCESS/FAILURE/CIRCUIT_OPEN/TIMEOUT/REJECTED)"
  - key: outcome
    type: string
    source: application_set
    required_in: [dependency]
    http_header_mapping: null
    envelope_field: null
    propagation: [none]
    owner_branch: feature-log-management-contract
    cardinality_safe_for_metric: true
    case_style: snake
    compatibility_impact: none
    required_test: contract-verification:log-fields

  # source: feature-log-management-contract.md L106 "dependency | ... error_code (실패 시)"
  # NOTE: metrics L89 "error_code | 100 — error registry row 상한과 정합" — bounded
  - key: error_code
    type: string
    source: application_set
    required_in: [dependency]
    http_header_mapping: null
    envelope_field: null
    propagation: [none]
    owner_branch: feature-log-management-contract
    cardinality_safe_for_metric: true
    case_style: snake
    compatibility_impact: none
    required_test: contract-verification:log-fields

  # source: feature-log-management-contract.md L107
  #   "security | event_type, user_principal (pseudonymized), source_ip (anonymized — last octet zeroed)"
  - key: event_type
    type: string
    source: application_set
    required_in: [security, audit]
    http_header_mapping: null
    envelope_field: null
    propagation: [none]
    owner_branch: feature-log-management-contract
    cardinality_safe_for_metric: true
    case_style: snake
    compatibility_impact: none
    required_test: contract-verification:log-fields

  # source: feature-log-management-contract.md L107 "security | ... source_ip (anonymized — last octet zeroed)"
  # NOTE: metrics L93 "high-cardinality 금지 tag: ... ip_address"
  - key: source_ip_anon
    type: string
    source: inbound_filter
    required_in: [security]
    http_header_mapping: null
    envelope_field: null
    propagation: [none]
    owner_branch: feature-log-management-contract
    cardinality_safe_for_metric: false
    case_style: snake
    compatibility_impact: none
    required_test: contract-verification:log-fields

  # source: feature-log-management-contract.md L108 "audit | actor, action, target, before_hash, after_hash, occurred_at"
  - key: actor
    type: string
    source: security_context
    required_in: [audit]
    http_header_mapping: null
    envelope_field: null
    propagation: [none]
    owner_branch: feature-log-management-contract
    cardinality_safe_for_metric: false
    case_style: snake
    compatibility_impact: none
    required_test: contract-verification:log-fields

  # source: feature-log-management-contract.md L108 "audit | actor, action, target, ..."
  - key: action
    type: string
    source: application_set
    required_in: [audit]
    http_header_mapping: null
    envelope_field: null
    propagation: [none]
    owner_branch: feature-log-management-contract
    cardinality_safe_for_metric: true
    case_style: snake
    compatibility_impact: none
    required_test: contract-verification:log-fields

  # source: feature-log-management-contract.md L108 "audit | actor, action, target, ..."
  - key: target
    type: string
    source: application_set
    required_in: [audit]
    http_header_mapping: null
    envelope_field: null
    propagation: [none]
    owner_branch: feature-log-management-contract
    cardinality_safe_for_metric: false
    case_style: snake
    compatibility_impact: none
    required_test: contract-verification:log-fields