llm-wiki/raw/official-docs/container-stdout-logging-12factor-official.md

title, source_type, url, archive_url, vendor, related_branches, related_projects, tags, created

title	source_type	url	archive_url	vendor	related_branches	related_projects	tags	created
Twelve-Factor App — XI. Logs (Factor 11: Treat logs as event streams)	official-doc	https://12factor.net/logs		Heroku / Adam Wiggins	feature-log-management-contract		official-doc ca-skeleton observability twelve-factor stdout-logging log-routing	2026-06-13

Twelve-Factor App — XI. Logs (Factor 11: Treat logs as event streams)

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/에 별도 작성. 원본은 raw에 영구 보관.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-log-management-contract	D4: production logging = stdout JSON default; file logging = local/dev only — 앱은 로그 라우팅·저장을 절대 직접 관리하지 않으며, 각 프로세스는 이벤트 스트림을 unbuffered 로 stdout 에 기록하고, 수집·라우팅은 실행 환경(컨테이너 런타임/플랫폼)이 담당한다는 Twelve-Factor 표준의 직접 근거

출처 / Source

• 원본 URL: https://12factor.net/logs
• 아카이브 URL: (없음 — 사용자 archive_url 미제공)
• 저자 / 조직: Adam Wiggins / Heroku (The Twelve-Factor App)
• 발행일: 2011년경 (원문 날짜 미표기)
• 마지막 확인일: 2026-06-13

왜 저장했는지 / Why archived

feature-log-management-contract D4("production logging = stdout JSON default; file logging = local/dev only")가 UNSUPPORTED_DECISION으로 표기되어 있었으며, 이를 뒷받침할 canonical industry standard가 필요했다. Twelve-Factor App Factor XI("Logs")는 앱이 로그 라우팅/저장을 관리해선 안 된다는 원칙의 직접적·공식적 출처다. D4를 UNSUPPORTED_DECISION에서 official-standard 근거 기반으로 승격하는 유일한 primary source.

핵심 인용 / Key quotes (verbatim, 5문장)

[§XI Logs, para 3] "A twelve-factor app never concerns itself with routing or storage of its output stream. It should not attempt to write to or manage logfiles. Instead, each running process writes its event stream, unbuffered, to stdout."

[§XI Logs, para 3, cont.] "During local development, the developer will view this stream in the foreground of their terminal to observe the app's behavior."

[§XI Logs, para 4] "In staging or production deploys, each process' stream will be captured by the execution environment, collated together with all other streams from the app, and routed to one or more final destinations for viewing and long-term archival."

[§XI Logs, para 4, cont.] "These archival destinations are not visible to or configurable by the app, and instead are completely managed by the execution environment."

[§XI Logs, para 1] "Logs are the stream of aggregated, time-ordered events collected from the output streams of all running processes and backing services."

Claims Extracted / 추출된 주장

이 자료가 직접 말하는 것만 claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
LOG-12F-C1	Twelve-Factor 앱은 로그의 라우팅·저장을 스스로 관리해선 안 된다 — logfile 쓰기·관리 시도 금지	[§XI para 3] "A twelve-factor app never concerns itself with routing or storage of its output stream. It should not attempt to write to or manage logfiles."	official-standard	Twelve-Factor 방법론을 따르는 모든 서버사이드 앱 (언어·프레임워크 무관)	특정 컨테이너 런타임(Docker/K8s) 또는 프레임워크(Spring Boot)의 구체적 설정값을 직접 증명하지 않음. stdout JSON 포맷(구조화 여부)에 대한 언급 없음
LOG-12F-C2	각 실행 중인 프로세스는 이벤트 스트림을 unbuffered 로 stdout 에 기록한다	[§XI para 3] "each running process writes its event stream, unbuffered, to stdout."	official-standard	모든 Twelve-Factor 앱 프로세스	특정 로그 포맷(JSON vs plain text)을 강제하지 않음. unbuffered 구현 방법(JVM flush 설정 등)을 명시하지 않음
LOG-12F-C3	staging/production 에서는 실행 환경이 프로세스 스트림을 캡처하고 앱의 모든 스트림과 합쳐 최종 목적지(장기 보관 포함)로 라우팅한다	[§XI para 4] "In staging or production deploys, each process' stream will be captured by the execution environment, collated together with all other streams from the app, and routed to one or more final destinations for viewing and long-term archival."	official-standard	Twelve-Factor 앱이 배포된 staging/production 환경	"실행 환경"의 구체적 구현(Logplex, Fluentd, Kubernetes logging driver 등)이 어떤 것이어야 하는지 규정하지 않음. 로컬 개발 환경에는 직접 적용되지 않음
LOG-12F-C4	로그 최종 아카이브 목적지는 앱에게 보이지 않으며 앱이 설정할 수 없고, 실행 환경이 완전히 관리한다	[§XI para 4] "These archival destinations are not visible to or configurable by the app, and instead are completely managed by the execution environment."	official-standard	production/staging 배포 환경의 앱 코드 레이어	로그 목적지(Splunk, Elasticsearch, CloudWatch 등) 선택의 우열을 규정하지 않음. 앱이 로그 메타데이터(structured fields)를 풍부하게 제공하는 것의 금지를 의미하지 않음
LOG-12F-C5	로그는 모든 실행 중인 프로세스와 backing service 의 출력 스트림에서 수집된 집계된·시간 순서 이벤트 스트림이다 — 고정된 시작/끝이 없으며 앱 동작 중 지속적으로 흐른다	[§XI para 1] "Logs are the stream of aggregated, time-ordered events collected from the output streams of all running processes and backing services. [...] Logs have no fixed beginning or end, but flow continuously as long as the app is operating."	official-standard	모든 Twelve-Factor 앱	로그가 반드시 구조화(JSON) 형식이어야 한다는 요구사항은 없음. 로그 sampling, 레벨 정책, MDC field 명세 등은 이 Factor 의 범위 밖

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • LOG-12F-C1: 앱 코드에서 logfile 직접 쓰기·관리는 Twelve-Factor 원칙 위반임
  • LOG-12F-C2: 각 프로세스가 stdout 으로 unbuffered 출력하는 것이 표준 구현 방식임
  • LOG-12F-C3: staging/prod 에서 스트림 캡처·라우팅은 실행 환경의 책임임 (앱 책임 아님)
  • LOG-12F-C4: 앱은 로그 목적지를 알 필요도, 설정할 권한도 없음
  • LOG-12F-C5: 로그의 개념적 정의 (스트림, 시간 순서, 연속성)
• 이 자료가 증명하지 않는 것:
  • stdout 로그의 포맷 (JSON vs plain-text) — 포맷 선택은 별도 근거 필요 (ECS, OTel, Logstash 등)
  • unbuffered 의 구체적 구현 (JVM 의 -Djava.util.logging.manager 설정, Spring Boot Logback flush 정책 등)
  • 로그 sampling 비율 (D5 의 prod 10% / WARN·ERROR 100% 정책은 별도 근거 없음 — UNSUPPORTED_DECISION)
  • Kubernetes 또는 Docker 에서의 구체적 container logging driver 설정
  • Spring Boot logback-spring.xml 의 <springProfile> 분기 (D10) 구현 방법
  • file appender 를 절대 써선 안 된다는 결론 — "local/dev 에서 파일 로그를 사용하는 것"은 Factor XI 를 위반하지 않음 (개발자가 터미널 외 파일로 보는 것은 허용 패턴). 단, production 에서 앱이 직접 logfile 을 관리하는 것은 위반
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • Spring Boot + Logback + logstash-logback-encoder 조합에서 stdout 출력이 실제로 unbuffered 인지 (JVM 버퍼링 여부) — locally-verified 필요
  • FILE_ENABLED=true 가 local/dev 에만 적용되는지 환경 게이트 검증 — D4 구현 현황에서 toggle 은 actually-implemented 이나 prod 오활성화 방지 테스트 별도 필요
  • K8s 배포 환경에서 stdout → container runtime → logging driver 체인의 실제 동작 확인 (Logplex/Fluentd 대안)

메모 / Notes

• Factor XI 는 로그 포맷을 규정하지 않는다. JSON 구조화 로그(D1)는 별도 근거(log-logback-mask-pattern-converter-official, log-ecs-schema-elastic-official)에서 뒷받침된다.
• config-12-factor-app-config.md(Factor III) 와 같은 출처(12factor.net)이며, 같은 방법론의 다른 Factor 다.
• 추가로 봐야 할 동일 출처 페이지: https://12factor.net (전체 12 Factors 개요) — 특히 Factor III(Config), Factor IX(Disposability), Factor XII(Admin processes)가 ca-tmpl 운영 계약과 연관됨.

Related / 관련

• 같은 출처 다른 Factor: raw/official-docs/config-12-factor-app-config (Factor III — 환경 변수 설정)
• 같은 주제 다른 official-doc: raw/official-docs/log-logback-mask-pattern-converter-official (D1/D10 근거), raw/official-docs/log-ecs-schema-elastic-official (D6 근거), raw/official-docs/log-otel-log-data-model-spec (D7 근거)
• 이 자료를 인용하는 branch: raw/branch-notes/feature-log-management-contract (D4 Decision Evidence Map)
• 이 자료를 인용한 wiki 요약: (미생성 — /ingest 후 wiki/concepts/ 에 작성)