llm-wiki/raw/official-docs/log-logback-mask-pattern-converter-official.md

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title	source_type	url	archive_url	status	confidence	tags	related_projects	related_branches	created	last_reviewed
Logback — PatternLayout converter / MDC masking	official-doc	https://logback.qos.ch/manual/layouts.html		raw	high	ca-log-management logback masking redaction pii official-doc	ca-skeleton-operational-contract	feature-log-management-contract	2026-05-22	2026-05-27

Logback — PatternLayout converter / MDC masking

Layer: raw/official-docs/ — Logback 공식 매뉴얼 layouts.html 의 PatternLayout / Converter extension / %replace 절 verbatim 발췌.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-log-management-contract	ca-tmpl "Layer 1 (primary) = Logback masking converter (PatternLayout 단계)" 채택 결정의 1차 근거
raw/project-notes/ca-skeleton-operational-contract	Group G-A (Log management) Redaction Layer 의 ca-tmpl 채택안 baseline

컨텍스트

ca-tmpl이 채택한 "Layer 1 (primary) = Logback masking converter (PatternLayout 단계)"의 근거 검증. token/password/auth header pattern을 ****로 치환하는 책임이 Logback PatternLayout 레벨에서 처리 가능한지 공식 spec으로 확인.

출처 / Source

• 원본 URL: https://logback.qos.ch/manual/layouts.html
• 아카이브 URL: (미수집)
• 저자 / 조직: QOS.ch (Logback)
• 발행일: rolling docs (Logback 1.x)
• 마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§PatternLayout — intro] "Logback classic ships with a flexible layout called PatternLayout. As all layouts, PatternLayout takes a logging event and returns a String. However, this String can be customized by tweaking PatternLayout's conversion pattern."

[§PatternLayout — intro] "The conversion pattern of PatternLayout is closely related to the conversion pattern of the printf() function in the C programming language."

[§Conversion specifier syntax] "A conversion pattern is composed of literal text and format control expressions called conversion specifiers. Each conversion specifier starts with a percent sign '%' and is followed by optional format modifiers, a conversion word and optional parameters between braces."

[§Creating a custom conversion specifier] "Building a custom conversion specifier consists of two steps... First, you must extend the ClassicConverter class... In the second step, we must let logback know about the new Converter. For this purpose, we need to declare the new conversion word in the configuration file." (예시: <conversionRule conversionWord="nanos" converterClass="chapters.layouts.MySampleConverter" />)

[§MDC converter] "Outputs the MDC (mapped diagnostic context) associated with the thread that generated the logging event. If the mdc conversion word is followed by a key between braces, as in %mdc{userid}, then the MDC value corresponding to the key 'userid' will be output."

[§replace converter] "%replace(p){r, t} Replaces occurrences of 'r', a regex, with its replacement 't' in the string produces by the sub-pattern 'p'."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
LOG-LBK-C1	Logback PatternLayout 은 logging event 를 String 으로 변환하며, C printf() 와 유사한 conversion pattern 으로 출력 형식을 커스터마이즈	[§PatternLayout — intro] "Logback classic ships with a flexible layout called PatternLayout. ... takes a logging event and returns a String. ... The conversion pattern of PatternLayout is closely related to the conversion pattern of the printf() function in the C programming language."	official-vendor-doc	Logback classic 사용 환경	structured JSON encoder (logstash-logback-encoder 등) 가 PatternLayout 위에서 동작한다는 뜻은 아님 — 별도 encoder 메커니즘
LOG-LBK-C2	conversion specifier 의 정확한 문법: % + optional format modifier + conversion word + optional {...} parameters	[§Conversion specifier syntax] "A conversion pattern is composed of literal text and format control expressions called conversion specifiers. Each conversion specifier starts with a percent sign '%' and is followed by optional format modifiers, a conversion word and optional parameters between braces."	official-vendor-doc	PatternLayout 패턴 작성	brace 내부 인자가 정규식이라는 등 의미 단위 해석은 converter 별로 다름
LOG-LBK-C3	사용자는 ClassicConverter 를 extends 한 뒤 logback config 의 <conversionRule> 로 새 conversion word 를 등록할 수 있음	[§Creating a custom conversion specifier] "Building a custom conversion specifier consists of two steps... First, you must extend the ClassicConverter class... In the second step, we must let logback know about the new Converter. ... we need to declare the new conversion word in the configuration file."	official-vendor-doc	custom converter (e.g., masking) 구현	converter 의 hot-reload (config 변경 시 즉시 반영) 가 모든 환경에서 동작한다는 뜻은 아님
LOG-LBK-C4	%mdc{key} 형식으로 MDC 의 특정 key 값을 출력 가능. MDC 는 현재 thread 에 연결된 mapped diagnostic context	[§MDC converter] "Outputs the MDC (mapped diagnostic context) associated with the thread that generated the logging event. If the mdc conversion word is followed by a key between braces, as in %mdc{userid}, then the MDC value corresponding to the key 'userid' will be output."	official-vendor-doc	MDC 기반 contextual logging	MDC 가 async/reactive thread 전환 시 자동 전파된다는 뜻은 아님 — 별도 propagation 메커니즘 필요
LOG-LBK-C5	%replace(p){r, t} converter 는 sub-pattern p 의 출력에 대해 정규식 r 매칭을 replacement t 로 치환 — 공식 built-in masking 메커니즘	[§replace converter] "%replace(p){r, t} Replaces occurrences of 'r', a regex, with its replacement 't' in the string produces by the sub-pattern 'p'."	official-vendor-doc	PatternLayout 기반 마스킹	regex 가 모든 PII 형식 (Base64 token 등) 을 catch 한다는 뜻은 아님 — false negative 가능

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • LOG-LBK-C1, C2: PatternLayout 의 정의와 conversion specifier 문법
  • LOG-LBK-C3: custom converter 등록 절차 (ClassicConverter + <conversionRule>)
  • LOG-LBK-C4: MDC converter 의 정확한 문법
  • LOG-LBK-C5: %replace(p){r, t} 가 공식 built-in 정규식 치환 converter 임
• 이 자료가 증명하지 않는 것:
  • "Logback 이 built-in PII masking converter 를 제공하지 않는다" 는 명제 — 본 페이지 인용으로 부재를 증명하지 않음 (다른 페이지/모듈 가능성 잔존). 따라서 이전 노트의 부재 진술은 검증 약화 필요.
  • ReplacingCompositeConverter 라는 정확한 클래스명은 본 페이지 인용에 없음 — %replace converter 의 implementation class 명은 별도 확인.
  • regex 기반 masking 의 performance overhead 정량값
  • exception cause chain message 가 %replace 적용 대상에 자동 포함되는지
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • ca-tmpl 의 logback.xml 에서 %replace(%msg){'(?i)(token|password)=\\S+', '$1=****'} 형식이 expected 동작하는지 단위테스트
  • structured JSON encoder (logstash-logback-encoder) 와 %replace 의 적용 순서 (encoder 가 PatternLayout 을 우회하면 마스킹 누락)
  • exception stack trace 마스킹은 %throwable converter wrapping 필요 여부

메모 / Notes (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

• %replace(p){r, t} built-in converter: PatternLayout에서 정규식 치환 지원. 예: %replace(%msg){'(?i)(token|password)=\\S+', '$1=****'}. ca-tmpl Layer 1의 1차 구현 후보.
• custom converter (권장): ClassicConverter를 상속, 마스킹 규칙을 코드로 관리. yaml/properties로 패턴 외부화 가능.
• Layer 1 SSOT 적정성: Logback이 final encoder 직전에 동작하므로, MDC, message, exception stack trace 전부가 converter를 통과 → 누락 risk 최소. Jackson serialize 단계(Layer 2)는 DTO field만, request body capture filter(Layer 3)는 inbound body만 커버. Layer 1이 가장 넓은 catch-net.
• 장점: library-agnostic (어떤 logger.info도 통과), 운영 hot-reload 가능 (logback.xml refresh), 표준 mechanism.
• 단점: regex 기반이라 false negative 가능 (Base64 encoded token 등). performance overhead (모든 log line 대상). exception cause chain의 message는 별도 처리 필요.
• ca-tmpl과의 차이: Layer 1 SSOT 결정과 정확히 일치. Layer 2/3는 보완 layer.

Related / 관련

• 같은 주제 다른 official-doc:
  • raw/official-docs/log-ecs-schema-elastic-official (log field 표준의 다른 측면)
  • raw/official-docs/log-otel-log-data-model-spec (대안 emit 경로)
• 적용 branch / contract:
  • raw/branch-notes/feature-log-management-contract
  • canonical contract: raw/project-notes/ca-skeleton-operational-contract §8 Structured Log Contract
• 대안 그룹: Group G-A — Log management (Redaction Layer)
• 본 source 위치: ca-tmpl 채택안 — Logback PatternLayout converter (Layer 1 SSOT)
• 인용하는 wiki: (미작성)