101 lines
9.5 KiB
Markdown
101 lines
9.5 KiB
Markdown
---
|
|
title: Logback — PatternLayout converter / MDC masking
|
|
source_type: official-doc
|
|
url: https://logback.qos.ch/manual/layouts.html
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [ca-log-management, logback, masking, redaction, pii, official-doc]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
related_branches: [feature-log-management-contract]
|
|
created: 2026-05-22
|
|
last_reviewed: 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: (미작성)
|