AI 서버 로그 수집 및 관리 - 100-hours-a-week/KTB4-10th-Cloud GitHub Wiki

1. 목적

AI 서버 애플리케이션 로그 중앙 수집 및 조회
개발 및 부하 테스트 중 오류/LLM 호출 로그 확인

로그 수집 구조

AI Application
       ↓
JSON stdout / stderr
       ↓
Docker json-file
       ↓
CloudWatch Agent
       ↓
CloudWatch Logs

CloudWatch 사용 이유

AI 서버의 애플리케이션 로그를 EC2에 직접 접속하지 않고 중앙 조회 가능
컨테이너 로컬 로그와 별도로 일정 기간 보관하기 위해 CloudWatch Logs를 사용
장애 및 부하 테스트 시 필요한 로그를 검색하고 원인을 추적하는 용도로 활용

역할 분리

Application
→ 로그 생성

Docker
→ stdout / stderr 로그를 로컬 파일에 저장

CloudWatch Agent
→ Docker 로그 파일 수집 및 전송

CloudWatch Logs
→ 로그 중앙 저장 및 조회

2. AI 애플리케이션 로그

환경

FastAPI / Uvicorn
필요한 애플리케이션 로그를 JSON 형식으로 stdout에 출력

예시:

{
  "time": "2026-09-30T14:32:02.652+09:00",
  "level": "INFO",
  "event": "llm_call",
  "llm_mode": "true",
  "elapsed_sec": 50.0
}

Uvicorn Access Log

--no-access-log 적용
- 요청별 Access Log 비활성화
- 부하 테스트 시 요청 수만큼 Access Log가 발생하는 것 방지

3. Docker 로그 저장

Logging Driver 확인

docker inspect kgb-ai --format '{{json .HostConfig.LogConfig}}'

확인 결과:

{"Type":"json-file","Config":{}}

Logging Driver: json-file
애플리케이션의 stdout/stderr를 EC2 로컬 Docker 로그 파일에 저장

로그 파일 위치 확인

docker inspect kgb-ai --format '{{.LogPath}}'

/var/lib/docker/containers/<container-id>/<container-id>-json.log

Docker json-file 로그는 컨테이너별 파일로 관리됨.

4. CloudWatch Agent

EC2에 CloudWatch Agent 설치 후 Docker 로그 파일 수집. 로그 섹션 참조

Agent 역할

Docker json-file 로그 수집
CloudWatch Logs 전송
Metric 수집 기능은 Prometheus로 수집 중이므로 CloudWatch Agent에서는 로그 수집만 담당하도록 구성.

5. 로그 수집 경로

Docker 로그 파일에는 Container ID가 포함됨.

/var/lib/docker/containers/<container-id>/<container-id>-json.log

컨테이너 재생성 시 Container ID가 변경되므로 특정 ID를 설정에 고정하지 않음.

현재 수집 경로:

/var/lib/docker/containers/*/*-json.log

현재 제약

현재 AI EC2에서 실행되는 Docker 컨테이너의 로그를 wildcard로 수집.

동일 EC2에서 여러 컨테이너가 실행될 경우 다른 컨테이너의 로그까지 함께 수집될 수 있음.

추후 필요 시:

수집 대상 분리
Log Group 분리
불필요한 컨테이너 로그 제외

6. IAM 권한

AI EC2에 연결된 IAM Role에 다음 AWS 관리형 Policy 추가.

CloudWatchAgentServerPolicy

구조:

AI EC2
  ↓
IAM Role
  ↓
CloudWatchAgentServerPolicy
  ↓
CloudWatch Agent
  ↓
CloudWatch Logs

CloudWatch Agent의 로그 전송 권한 확보
Policy에는 Metric 관련 권한도 포함
현재 Agent 설정에서는 로그 수집만 사용

7. CloudWatch Agent 설정

Agent 설정

설정 파일

sudo nano /opt/aws/amazon-cloudwatch-agent/etc/cloudwatch-agent.json

설정

{
  "agent": {
    "region": "ap-northeast-2"
  },
  "logs": {
    "logs_collected": {
      "files": {
        "collect_list": [
          {
            "file_path": "/var/lib/docker/containers/*/*-json.log",
            "log_group_name": "/kgb/ai/prod/application",
            "log_stream_name": "{instance_id}"
          }
        ]
      }
    }
  }
}

설정값

Region
→ ap-northeast-2

수집 경로
→ /var/lib/docker/containers/*/*-json.log

Log Group
→ /kgb/ai/prod/application

Log Stream
→ {instance_id}

Log Stream에 EC2 Instance ID를 사용해 로그 발생 인스턴스를 구분.

CloudWatch Agent 설정 파일의 logs 및 collect_list 구조는 AWS 공식 설정 형식 사용.

8. Agent 설정 적용

설정 적용 및 Agent 시작

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
  -a fetch-config \
  -m ec2 \
  -s \
  -c file:/opt/aws/amazon-cloudwatch-agent/etc/cloudwatch-agent.json

옵션

-a fetch-config
→ 작성한 설정을 Agent에 적용

-m ec2
→ EC2 환경에서 실행

-s
→ 설정 적용 후 Agent 시작

-c file:...
→ 사용할 설정 파일 지정

Agent 상태 확인

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a status

확인 결과

CloudWatch Agent 정상 실행
/kgb/ai/prod/application Log Group 생성 확인
EC2 Instance ID 기반 Log Stream 생성 확인
AI 애플리케이션 로그 유입 확인

9. 로그 보존

CloudWatch Logs

보존 기간: 7일

선택 이유:

장기 운영 서비스가 아닌 개발 단계
최근 장애 로그 확인 목적
부하 테스트 결과 확인 목적
장기 로그 보관 필요성 낮음

Docker 로컬 로그와의 차이

Docker json-file
→ EC2 로컬 디스크에 저장
→ 컨테이너 단위로 관리
→ 동일 컨테이너가 유지되는 동안 로그 누적 가능

CloudWatch Logs
→ CloudWatch Agent가 전송한 로그 저장
→ 보존 기간 7일 적용

CloudWatch Logs의 7일 보존 정책은 Docker 로컬 json-file 로그의 보관 기간과 무관함.

docker restart는 동일 컨테이너를 재시작하므로 기존 json-file 로그 유지.

기존 컨테이너 삭제 후 새 컨테이너를 생성하는 경우 기존 컨테이너에 속한 로그 파일도 제거됨.

10. 개선 예정

Docker 로그 로테이션

현재 Docker json-file 설정:

{"Type":"json-file","Config":{}}

max-size, max-file 등 로그 크기 제한 미적용.

동일 컨테이너가 장기간 실행될 경우 로컬 로그 파일이 계속 증가해 EC2 디스크를 사용할 수 있음.

추후 로그 관리 정책 적용 예정.