문제: 앞 커밋이 레지스트리 주석의 `# source:`를 `# 출처:`로 바꾸고, 출처 줄 안의 기록 절 이름(「In scope」「Decisionized Work Items」「decisions」「Exposure Policy」「AuthN/AuthZ Decision Matrix」)까지 한국어로 옮겼다. 출처 줄은 기록 이름·날짜·절 이름으로 원문을 찾아가는 줄이라, 옮기면 그 기록에서 같은 이름을 찾을 수 없다. 또 metrics.yaml 주석 세 줄에 변환 실수로 `\"`(백슬래시가 붙은 따옴표)가 들어갔다. 고른 방법: 총괄 기준(2026-11-07)대로 나눈다. - 원문으로 둔다: 출처 줄의 꼬리표 `source:`, 기록 이름·날짜·절 이름, 따옴표 인용. - 한국어로 둔다: 같은 줄의 나머지 설명, 행마다의 이유·조건·주의 산문, 값 칸, 파일 머리 블록. - `\"`는 `"`로 고친다. 위험·한계: 출처가 가리키는 `feature-*` 계약 기록 24개는 저장소 어디에도(이력 포함) 그 이름의 파일이 없다. `docs/design/`에 있는 것은 `five-adapter-runtime-remediation`과 `redis-production-capability` 둘이고, 파일 이름에 날짜와 `-design`이 붙어 있다. 이름은 고치지 않았다. 검증: 여덟 파일을 `yaml.safe_load`로 읽은 데이터가 앞 커밋과 같다(주석만 바뀜). `python3 scripts/check-docs.py` rc=0.
294 lines
11 KiB
YAML
294 lines
11 KiB
YAML
# Registry: MDC / Log Keys
|
|
# Schema owner: feature-contract-registry-governance
|
|
# MDC SSOT: feature-operational-error-observability-foundation
|
|
# Last updated: 2026-05-22
|
|
#
|
|
# 표기 규칙
|
|
# - MDC key 이름: snake_case (foundation L93 "snake_case 강제. camelCase / dot.case 금지.")
|
|
# - cardinality_safe_for_metric=true 인 key만 metric tag로 사용 가능
|
|
# - foundation L93-102 표 "MDC Key Standard (final)"의 key들이 핵심 정본이다
|
|
|
|
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-management-contract L101-109 "Log Type별 필수 필드") ──
|
|
|
|
# source: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms"
|
|
# 참고: application-port-usecase-contract / 업무 쪽 operation 식별자 (uri_template과 따로 application이 정한다)
|
|
- 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"
|
|
# 참고: metrics L86 "status_code | 7 (1xx-5xx + ok/other)" — 값 개수가 정해져 있다
|
|
- 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"
|
|
# 참고: metrics L88 "dependency_name | 50" — 값 개수가 정해져 있다
|
|
- 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 (실패 시)"
|
|
# 참고: metrics L89 "error_code | 100 — error registry row 상한과 정합" — 값 개수가 정해져 있다
|
|
- 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
|