[feat] Loki·Alloy 로그 파이프라인 및 Grafana logs↔Trace 연결 (4/4)

[PHJ2000]

🔗 이슈 링크

• Related [feat] 관측 인프라 Terraform + cloud-init IaC 도입 #233 — 관측 인프라 Terraform + cloud-init IaC
• Related [Draft][bug] PR4 Alloy 로그 회전 누락 및 긴 JSON 분할 처리 보완 #263 — Alloy 로그 회전 누락 및 긴 JSON 재조립

🧩 이 PR의 변경사항

현재 관측 구성에는 Loki와 앱 측 로그 수집기가 없어 Grafana에서 backend 로그를 조회하거나 해당 Trace로 이동할 수 없다. 앱 서버의 Docker 로그를 Alloy로 수집해 관측 서버의 Loki에 저장하고, Grafana에서 로그와 Trace를 양방향으로 조회하도록 구성한다.

전체 중 위치

• #233의 4/4 단계: 로그 파이프라인
• 선행 PR: feat: 관측 스택 Compose 및 자동 부트스트랩 구성 (3/4) #238 — 관측 런타임 기반, 머지 완료

이 PR에서 변경한 것

• Loki 컨테이너와 EBS 하위 저장 경로를 추가한다. 보존 기간은 dev 72h, staging 168h, prod 336h로 설정한다.
• Loki TCP 3100은 앱 서버 Security Group에서만 접근하도록 제한한다.
• Alloy는 Docker 로그 디렉터리를 읽기 전용으로 마운트하고 beach.logs=backend인 로그만 수집한다. Docker 소켓은 사용하지 않는다.
• 현재 파일과 회전된 파일을 오래된 순서로 읽고, 파일 지문과 읽기 위치를 Docker 볼륨에 저장한다.
• Docker가 나눈 한 줄은 컨테이너와 stdout/stderr별로 재조립한다. 인덱스 라벨은 app, env, service, host만 유지한다.
• Grafana Loki 데이터 소스, traceId 링크, Tempo의 Trace to logs 쿼리를 추가한다.
• 앱 Compose 예제, 로그 설정 override, 로컬 통합 검증 및 CI를 추가한다.

✅ 이 PR이 커버하는 AC

Covers — 코드 및 로컬 검증

• AC2의 PR4 범위: TCP 3100에 앱 SG만 허용하는 규칙을 Terraform mock plan으로 확인했다.
• AC6·AC7 관련: Loki 데이터 소스 연결, JSON·traceId 검색, 인덱스 라벨 4개를 확인했다.
• AC9: cloud-init schema와 압축 user data 크기 7,725/16,384바이트를 확인했다.
• AC12의 Loki 범위: 72h 보존 설정과 컨테이너 재생성 후 데이터 조회를 확인했다.
• AC13 관련: Grafana 연결 설정과 proxy API를 통한 Trace·역방향 로그 조회를 확인했다.
• PR4 읽기 위치 복원: Alloy 중지 중 회전된 110건을 모두 복구했다. 재생성 후에는 전송 카운터로 기존 기록이 다시 전송되지 않는지 확인했다.
• [Draft][bug] PR4 Alloy 로그 회전 누락 및 긴 JSON 분할 처리 보완 #263 긴 JSON: 두 컨테이너의 stdout/stderr 조각이 교차하는 40KB JSON과 회전 파일 경계에 걸친 90KB JSON이 원문과 일치했다.

Not covered — 서버 적용 후 #233에서 확인

• AC3·AC5: 실제 EC2 부팅·재부팅, 앱 서버 Alloy 기동, EBS 저장 경로 확인
• AC6·AC7·AC12: 실제 앱 로그 조회·라벨 확인, EBS 데이터 보존 및 보존 기간 경과 후 삭제
• AC13: 실제 앱 로그·span 연결과 Grafana 브라우저에서 Trace 이동

합성 데이터와 로컬 Docker 볼륨으로 검증했으며, #233의 서버 AC 전체가 완료된 것은 아니다. SLI/SLO·알림·대시보드·S3 원격 상태 저장소·24시간 운영 검증은 상위 이슈에서 분리한 후속 범위다.

🧪 테스트 결과

로컬

bash deploy/observability/scripts/validate-iac.sh
python3 deploy/observability/scripts/verify-log-pipeline.py
git diff --check

• Terraform fmt/init/validate, mock plan 3건, cloud-init schema·크기, Compose 및 Loki/Alloy 설정 검사 통과
• 실제 Docker 로그 수집, 회전 복구, 긴 JSON 재조립, 중복 전송 방지, Grafana 연결, Loki 장애 복구·데이터 보존 등 9항목 통과
• 보고서: build/reports/observability/log-pipeline.json — CI artifact에도 보관

CI

• 2ef5d045: Observability IaC Validation, Backend Build & Test (Unit + Integration) 모두 통과
• GitHub Actions 실행 결과

Smoke 테스트

• 로컬: 합성 JSON 로그 → Docker → Alloy → Loki → Grafana 조회 및 합성 OTLP Trace 연결
• 서버: 미실행. 실제 앱 로그와 브라우저 이동은 #233에 남겨 둔다.

🧭 영향 범위 체크

• API 변경
• DB 변경
• 설정 변경: Loki/Alloy/Grafana, SG 3100, Docker logging, cloud-init, CI
• Breaking change

기존 user_data_replace_on_change = true 때문에 실제 apply 시 관측 EC2가 교체될 수 있다. 적용 전에 실제 state 기준 plan과 EBS 보존 여부를 확인해야 한다. 앱 로그 속성은 컨테이너 재생성 시 적용되며, 지속 배포에 사용하는 Compose에도 유지해야 한다.

💬 리뷰 포인트

• app-agent/alloy/config.alloy: 회전 파일 읽기 순서, 파일 지문, 컨테이너·출력 스트림별 재조립, 라벨 제한
• scripts/verify-log-pipeline.py: 실제 Docker 회전·분할 기록을 사용한 회귀 테스트와 전송 카운터 검증
• compose/loki/local-config.yaml, Grafana provisioning, Terraform/cloud-init: 저장 경로·보존 기간·SG·로그와 Trace 연결

Alloy v1.19.2의 filelog receiver와 file storage는 공개 미리보기 기능이다. 버전을 고정하고 실행·검증에 해당 옵션을 명시했다. 이 버전의 정렬 옵션 매핑 문제 때문에 내부 file_input 연산자에 정렬을 직접 설정한다. 배경과 제거 조건은 README와 설정 주석에 기록했다.

재조립 중인 조각은 메모리에만 있다. 첫 조각을 읽은 뒤 5초 안에 한 줄이 완성되지 않거나 재조립 도중 수집기가 종료되면 원문 보존을 보장하지 않는다. 읽기 위치 저장과 Loki 전송 완료도 원자적으로 묶이지 않으므로 무손실·exactly-once 전송을 보장하지 않는다. 로그 한 줄은 256KiB 이내로 유지하고 Docker는 압축 없이 최대 5개 파일을 보존한다.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: d92a83e3-5b22-4803-903e-f5dcbad607ec

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[geonusp]

pr 리뷰 결과 지금 규모에서 운영 상에 큰 문제가 생길만한 부분은 없어 보이므로 Approve하겠습니다. 밑에 코멘트에 답만 달아주시면 머지하겠습니다.