llm-wiki/raw/official-docs/ecs-awslogs-stdout-cloudwatch-aws-official.md

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

title	source_type	url	archive_url	related_branches	related_projects	tags	created
Send Amazon ECS logs to CloudWatch — awslogs log driver	official-doc	https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using_awslogs.html		feature-log-management-contract	ca-skeleton	official-doc ca-skeleton observability aws stdout-logging log-routing	2026-06-13

Send Amazon ECS logs to CloudWatch — awslogs log driver

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

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-log-management-contract	D4 — "production logging = stdout JSON default, file logging local/dev only": awslogs 드라이버가 컨테이너 stdout/stderr 를 Docker 를 거쳐 CloudWatch Logs 로 전달하므로, 앱은 로그 파일 직접 전달 책임을 갖지 않는다. 플랫폼(ECS+awslogs)이 스트림을 수집하므로 stdout 출력만으로 운영 로그 수집이 완결된다.

출처 / Source

• 원본 URL: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using_awslogs.html
• 아카이브 URL: (미제공)
• 저자 / 조직: Amazon Web Services
• 발행일: (ongoing — AWS 공식 문서, 지속 갱신)
• 마지막 확인일: 2026-06-13

왜 저장했는지 / Why archived

feature-log-management-contract D4 결정("production logging = stdout JSON default")은 "앱이 로그 파일을 직접 관리·전달하지 않는다"는 런타임 가정에 근거한다. 이 자료는 그 가정의 직접 근거: AWS ECS 공식 문서가 awslogs 드라이버가 컨테이너 stdout/stderr 를 Docker 를 거쳐 CloudWatch Logs 로 단순 전달(pass-through)함을 명시하며, 앱 쪽 별도 로그 shipper 가 필요 없음을 확인한다.

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

[§Note — Log source] "The type of information that is logged by the containers in your task depends mostly on their ENTRYPOINT command. By default, the logs that are captured show the command output that you typically might see in an interactive terminal if you ran the container locally, which are the STDOUT and STDERR I/O streams. The awslogs log driver simply passes these logs from Docker to CloudWatch Logs."

[§Intro] "You can configure the containers in your tasks to send log information to CloudWatch Logs. If you're using Fargate for your tasks, you can view the logs from your containers. If you're using EC2, you can view different logs from your containers in one convenient location, and it prevents your container logs from taking up disk space on your container instances."

[§Fargate] "If you're using Fargate for your tasks, you need to add the required logConfiguration parameters to your task definition to turn on the awslogs log driver."

[§EC2] "If you're using EC2 for your tasks and want to turn on the awslogs log driver, your Amazon ECS container instances require at least version 1.9.0 of the container agent."

[§EC2 — IAM] "Your Amazon ECS container instances also require logs:CreateLogStream and logs:PutLogEvents permission on the IAM role that you can launch your container instances with."

Claims Extracted / 추출된 주장

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

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
LOG-ECS-AWSLOGS-C1	awslogs 드라이버는 컨테이너의 stdout/stderr 스트림을 Docker 를 통해 CloudWatch Logs 로 그대로 전달(pass-through)한다 — 앱 내부에 별도 로그 shipper 가 필요하지 않다	[§Note] "The awslogs log driver simply passes these logs from Docker to CloudWatch Logs."	official-vendor-doc	AWS ECS(Fargate 또는 EC2) + awslogs log driver 구성	다른 컨테이너 오케스트레이터(k8s, Nomad)나 다른 log driver(fluentd, splunk) 에서도 동일하게 동작한다는 뜻 아님. AWS-vendor 특화 동작.
LOG-ECS-AWSLOGS-C2	컨테이너 로그 캡처 대상은 기본적으로 ENTRYPOINT 커맨드의 stdout / stderr I/O 스트림이다	[§Note] "By default, the logs that are captured show the command output that you typically might see in an interactive terminal if you ran the container locally, which are the STDOUT and STDERR I/O streams."	official-vendor-doc	awslogs log driver 가 활성화된 ECS 태스크 컨테이너	파일에 쓴 로그나 syslog 가 자동으로 캡처된다는 뜻 아님. stdout/stderr 이외 스트림은 별도 처리 필요.
LOG-ECS-AWSLOGS-C3	ECS on EC2 환경에서 awslogs 를 활성화하면 컨테이너 로그가 컨테이너 인스턴스의 디스크 공간을 점유하지 않게 된다	[§Intro] "it prevents your container logs from taking up disk space on your container instances"	official-vendor-doc	EC2 launch type + awslogs driver	Fargate 에서는 로컬 디스크 관리 모델이 다름 (Fargate는 기본적으로 로컬 디스크 노출 없음).
LOG-ECS-AWSLOGS-C4	Fargate 에서 awslogs 드라이버를 활성화하려면 태스크 정의에 logConfiguration 파라미터를 명시해야 한다	[§Fargate] "you need to add the required logConfiguration parameters to your task definition to turn on the awslogs log driver"	official-vendor-doc	AWS Fargate launch type	EC2 launch type의 활성화 절차와 다름(EC2는 에이전트 버전 + IAM 정책 추가 필요).
LOG-ECS-AWSLOGS-C5	EC2 에서 awslogs 드라이버 사용 시 컨테이너 인스턴스의 IAM role 에 logs:CreateLogStream 및 logs:PutLogEvents 권한이 필요하다	[§EC2 — IAM] "Your Amazon ECS container instances also require logs:CreateLogStream and logs:PutLogEvents permission on the IAM role that you can launch your container instances with."	official-vendor-doc	EC2 launch type + awslogs driver	Fargate 의 경우 ecsTaskExecutionRole 을 통한 권한 모델이 다름. IAM 권한은 최소 필요 조건이며 충분 조건이 아닐 수 있음(네트워크/VPC endpoint 설정 등 추가 조건 있음).

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • LOG-ECS-AWSLOGS-C1: AWS ECS + awslogs log driver 조합에서 앱이 stdout 에만 쓰면 CloudWatch Logs 로 수집이 완결됨 — 별도 로그 shipper 불필요.
  • LOG-ECS-AWSLOGS-C2: awslogs 가 캡처하는 기본 대상은 stdout/stderr 이며, 파일 기반 로그는 별도 처리가 필요함.
  • LOG-ECS-AWSLOGS-C3: EC2 launch type 에서 awslogs 는 디스크 사용 방지 효과.
  • LOG-ECS-AWSLOGS-C4: Fargate 에서 awslogs 활성화는 태스크 정의 logConfiguration 필수.
  • LOG-ECS-AWSLOGS-C5: EC2에서 awslogs 동작에 필요한 최소 IAM 권한(logs:CreateLogStream, logs:PutLogEvents).
• 이 자료가 증명하지 않는 것:
  • stdout JSON 이 모든 컨테이너 런타임에서 기본 권장 로그 방식이라는 크로스-플랫폼 표준 — 이것은 AWS-vendor 특화 문서이며 Kubernetes, GCP Cloud Run, Azure Container Apps 에 동일하게 적용된다는 근거 없음.
  • 12-factor app 원칙 XI (Logs를 이벤트 스트림으로 다루어라)의 직접 인용 — 12-factor 와 논리적으로 일치하지만 본 문서는 그것을 명시하지 않음.
  • awslogs 가 JSON 형식을 강제하거나 권장한다는 내용 — 형식(JSON vs plain text)은 앱 책임이며 awslogs 는 형식에 무관하게 전달함.
  • CloudWatch Logs 에서의 파싱/필터/알람 설정 방법 — 별도 CloudWatch 문서 필요.
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • ca-tmpl 가 ECS(Fargate or EC2)에 실제 배포될 경우 logConfiguration 태스크 정의 설정 검증 필요.
  • 로컬/dev 환경은 ECS 없이 Docker Compose 로 운영 — FILE_ENABLED toggle(D4)이 로컬 환경에서 올바르게 동작하는지는 별도 검증 필요.

메모 / Notes

• LOG-ECS-AWSLOGS-C1 은 feature-log-management-contract D4 의 UNSUPPORTED_DECISION 을 official-vendor-doc 수준으로 부분 승격시키는 직접 근거다. 다만 "D4 의 근거가 AWS ECS 전용"임을 decision evidence map 에 명시해야 함 — 향후 non-AWS 환경(Kubernetes, on-prem)으로 이관 시 재검토 필요.
• awslogs 의 awslogs-delivery-mode 파라미터(blocking / non-blocking + max-buffer-size)는 비동기 버퍼 관련 — feature-log-management-contract 의 AsyncAppender overflow 정책(D8)과 유사 관심사이나 레이어가 다름(ECS 레벨 vs 앱 내부 레벨). 별도 raw source 추가 검토 가능.
• 추가로 봐야 할 동일 출처 페이지: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specify-log-config.html (태스크 정의 logConfiguration 예시)

Related / 관련

• 같은 주제 다른 official-doc / company-tech-blog:
  • raw/official-docs/log-otel-log-data-model-spec.md — OTel log signal 대안 (D7 근거)
  • raw/official-docs/log-ecs-schema-elastic-official.md — ECS log schema (D6 근거)
  • raw/official-docs/log-logback-mask-pattern-converter-official.md — Logback masking (D1/D2/D10 근거)
• 이 자료를 인용한 branch: raw/branch-notes/feature-log-management-contract
• 이 자료를 인용한 wiki 요약: (생성 시 추가)