DEPLOY - v1.0.2 by youyeon11 · Pull Request #31 · DearBelly/DearBelly-BE-FastAPI

youyeon11 · 2025-10-02T07:43:31Z

📌 작업 목적

🗂 작업 유형

🔨 주요 작업 내용

모니터링 환경을 추가하였습니다

📎 관련 이슈

Closes [FEATURE] Prometheus/Grafana 환경 추가 #30

[FEATURE] Prometheus/Grafana 환경 추가

gemini-code-assist · 2025-10-02T07:43:45Z

Summary of Changes

Hello @youyeon11, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

이 PR은 애플리케이션에 포괄적인 모니터링 기능을 도입하여 Prometheus와 Grafana를 통합합니다. FastAPI 애플리케이션을 계측하여 성능 메트릭을 노출하고, 배포 프로세스를 업데이트하며, 모니터링 스택에 필요한 구성 파일을 추가합니다. 이는 시스템의 가시성을 향상시키고 잠재적인 문제를 사전에 감지하는 데 도움이 될 것입니다.

Highlights

모니터링 환경 추가: 애플리케이션에 Prometheus와 Grafana를 포함한 포괄적인 모니터링 환경이 추가되었습니다.
FastAPI 메트릭 계측: FastAPI 애플리케이션에 prometheus-fastapi-instrumentator 라이브러리를 사용하여 /actuator/prometheus 엔드포인트에 메트릭을 노출하도록 계측되었습니다.
배포 스크립트 업데이트: deploy.sh 스크립트가 docker-compose.yml 파일을 명시적으로 참조하도록 업데이트되어 컨테이너 풀 및 재구축 프로세스의 명확성을 높였습니다.
새로운 모니터링 구성 파일: Prometheus 및 Grafana를 위한 docker-compose.monitoring.yml, Prometheus 경고 규칙을 위한 prometheus-rule.yml, 그리고 Prometheus 서버 구성을 위한 prometheus.yml 파일이 새로 추가되었습니다.
종속성 업데이트: requirements.txt 파일에 prometheus-client와 prometheus-fastapi-instrumentator가 추가되었습니다.

Ignored Files

Ignored by pattern: .github/workflows/** (1)
- .github/workflows/workflow.yml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

youyeon11 · 2025-10-02T07:44:50Z

🤖 Gemini 코드 리뷰 결과

1) PR 의도 요약

이번 PR은 시스템의 안정성과 관측 가능성(Observability)을 높이기 위해 Prometheus와 Grafana 기반의 모니터링 환경을 도입하는 것을 목표로 합니다. 이를 위해 FastAPI 애플리케이션에 메트릭 수집 엔드포인트를 추가하고, 모니터링 스택을 Docker Compose로 정의하였습니다. 또한, 인스턴스 다운이나 API 지연과 같은 상황에 대한 경고(Alert) 규칙을 설정하여 장애에 신속하게 대응할 수 있는 기반을 마련했습니다.

2) 전반적 평가 (품질/가독성/테스트/아키텍처)

컨벤션: 전반적으로 코드와 설정 파일들이 각 도구의 표준 컨벤션을 잘 따르고 있습니다. Python 코드는 PEP8을 준수하며, YAML 설정도 구조적으로 명확합니다.
네이밍/모듈 경계: docker-compose.monitoring.yml, prometheus.yml 등 파일명이 역할을 명확하게 나타내어 이해하기 쉽습니다. 모니터링과 애플리케이션 로직의 분리도 잘 이루어졌습니다.
의존성: 모니터링을 위한 의존성(prometheus-fastapi-instrumentator)이 requirements.txt에 명확히 추가되었습니다.
테스트 전략: 인프라 설정 변경이 주된 내용이므로 자동화된 테스트는 없지만, 배포 후 실제 모니터링 대시보드 및 알림 기능이 정상 동작하는지에 대한 수동 검증이 반드시 필요합니다.

3) 우선순위별 피드백 목록

[P2] 하드코딩된 경로를 사용하여 이식성 및 유지보수성 저하

파일/위치: deployment/docker-compose.monitoring.yml:6, deployment/docker-compose.monitoring.yml:23, .github/workflows/workflow.yml:48
근거(왜 문제인지): docker-compose.monitoring.yml 파일 내 볼륨 경로가 /home/ubuntu/... 와 같이 절대 경로로 하드코딩되어 있습니다. 이는 특정 사용자(ubuntu)와 특정 디렉토리 구조(dearbelly)에 강하게 의존하게 만듭니다. GitHub Actions 워크플로우의 target 경로도 마찬가지입니다.
영향(버그/보안/성능/유지보수 등):
- 유지보수성: 향후 서버 환경(예: 사용자 이름 변경, 프로젝트 경로 변경)이 바뀔 경우, 여러 설정 파일을 찾아 직접 수정해야 하므로 번거롭고 실수를 유발하기 쉽습니다.
- 이식성: 다른 개발자가 로컬 환경에서 테스트하거나, 다른 서버에 동일한 구성을 배포하기 어렵게 만듭니다.

제안(구체적 조치, 대안, 참고 링크는 선택):

Docker Named Volumes 사용: 데이터 저장 볼륨(prometheus/volume, grafana/volume)은 Docker가 관리하는 Named Volume으로 변경하는 것을 적극 권장합니다. 이렇게 하면 호스트 경로 의존성이 사라집니다.
설정 파일은 상대 경로 사용: prometheus.yml과 같은 설정 파일은 docker-compose 파일 위치 기준으로 상대 경로를 사용하도록 수정하는 것이 좋습니다.
GitHub Actions 경로는 Secret/Variable 사용: 배포 경로는 GitHub Actions의 Secret이나 Variable로 관리하면 유연성이 크게 향상됩니다.

수정 제안 (docker-compose.monitoring.yml):

services:
  prometheus:
    user: ${PROMETHEUS_USER}
    image: prom/prometheus:latest
    container_name: prometheus
    volumes:
-     - /home/ubuntu/dearbelly/deployment/prometheus.yml:/etc/prometheus/prometheus.yml:ro
-     - /home/ubuntu/prometheus/volume:/prometheus/data
+     - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
+     - prometheus-data:/prometheus/data
    ports:
      - 9090:9090
    # ... (이하 생략)

  grafana:
    user: ${GRAFANA_USER}
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - 3000:3000
    volumes:
-     - /home/ubuntu/grafana/volume:/var/lib/grafana
+     - grafana-data:/var/lib/grafana
    restart: always
    networks:
      - mynetwork

networks:
  mynetwork:
    driver: bridge

+volumes:
+  prometheus-data:
+  grafana-data:

[P2] 모니터링 스택 배포 자동화 누락

파일/위치: deployment/deploy.sh
근거(왜 문제인지): deploy.sh 스크립트는 docker-compose.yml 파일을 사용하여 애플리케이션(app-blue/app-green)만 배포하도록 구성되어 있습니다. 새로 추가된 docker-compose.monitoring.yml 파일의 서비스(Prometheus, Grafana)를 실행하는 로직이 포함되어 있지 않습니다.
영향(버그/보안/성능/유지보수 등):
- 배포 불완전성: 현재 배포 스크립트를 실행해도 모니터링 환경은 실행되지 않습니다. 매번 수동으로 docker compose -f docker-compose.monitoring.yml up -d 와 같은 명령을 실행해야 하므로, 배포 과정이 번거롭고 실수가 발생할 수 있습니다.
제안(구체적 조치, 대안, 참고 링크는 선택):
배포 스크립트가 모니터링 스택의 실행도 책임지도록 수정해야 합니다. 예를 들어, deploy.sh 상단에 모니터링 서비스를 실행(또는 업데이트)하는 구문을 추가할 수 있습니다.

수정 제안 (deploy.sh):
```
#!/bin/bash

+echo "Starting monitoring services..."
+docker compose -f docker-compose.monitoring.yml up -d
+
 EXIST_BLUE=$(docker compose -f docker-compose.yml ps -q app-blue)
 # ... (이하 기존 스크립트)
```
또는, 하나의 스크립트로 여러 compose 파일을 관리하는 것이 복잡하다면, 별도의 deploy-monitoring.sh 스크립트를 만들고 문서화하는 방법도 고려할 수 있습니다.

[P3] 환경 변수 설정에 대한 설명 부족

파일/위치: deployment/docker-compose.monitoring.yml:3, deployment/docker-compose.monitoring.yml:19, deployment/prometheus.yml:18 등
근거(왜 문제인지): docker-compose.monitoring.yml 과 prometheus.yml에서 ${PROMETHEUS_USER}, ${GRAFANA_USER}, ${REMOTE_HOST} 와 같은 환경 변수를 사용하고 있습니다. 하지만 이 변수들이 어디서 어떻게 설정되어야 하는지에 대한 설명(예: .env 파일 필요성)이 PR 본문이나 코드 내 주석에 없습니다.
영향(버그/보안/성능/유지보수 등):
- 실행 오류: 해당 환경 변수 없이 실행하면 서비스가 권한 문제로 시작에 실패하거나, 프로메테우스가 올바른 대상을 스크랩하지 못할 수 있습니다.
- 협업 비효율: 다른 팀원이 이 프로젝트를 새로 설정할 때, 어떤 환경 변수가 필요한지 몰라 시간을 낭비하거나 설정에 실패할 가능성이 높습니다.
제안(구체적 조치, 대안, 참고 링크는 선택):
프로젝트 루트에 .env.example 파일을 추가하여 필요한 환경 변수 목록과 그 역할을 설명해주세요. 이를 통해 다른 개발자들이 손쉽게 로컬 환경을 구성할 수 있습니다.

.env.example 파일 예시:
```
# docker-compose.monitoring.yml: Prometheus & Grafana services user ID/group ID
# Example: 1000:1000 or ubuntu user's id
PROMETHEUS_USER=1000:1000
GRAFANA_USER=472:472

# prometheus.yml: Host IP for Prometheus to scrape itself and node-exporter
REMOTE_HOST=127.0.0.1
```

[P3] API 메트릭 수집 주기 과다

파일/위치: deployment/prometheus.yml:28, deployment/prometheus.yml:32
근거(왜 문제인지): FastAPI 애플리케이션의 메트릭을 수집하는 scrape_interval이 1m(1분)으로 설정되어 있습니다.
영향(버그/보안/성능/유지보수 등):
- 장애 감지 지연: 트래픽 급증이나 응답 시간 지연과 같은 순간적인 문제가 발생했을 때, 이를 감지하는 데 최대 1분이 소요될 수 있습니다. 이는 장애 대응의 골든타임을 놓치게 할 수 있습니다.

제안(구체적 조치, 대안, 참고 링크는 선택):
애플리케이션 메트릭 수집 주기를 일반적인 수준인 15s 또는 30s로 줄이는 것을 제안합니다. 이렇게 하면 시스템 상태 변화를 더 빠르게 파악할 수 있습니다.

수정 제안 (prometheus.yml):

# ...
  - job_name: 'fastapi-actuator-blue'
    metrics_path: '/actuator/prometheus'
-   scrape_interval: 1m
+   scrape_interval: 15s
    static_configs:
      - targets: [ 'app-blue:8000' ]
  - job_name: 'fastapi-actuator-green'
    metrics_path: '/actuator/prometheus'
-   scrape_interval: 1m
+   scrape_interval: 15s
    static_configs:
      - targets: [ 'app-green:8001' ]

[P4] 불필요한 의존성 포함

파일/위치: requirements.txt:14
근거(왜 문제인지): logging 라이브러리가 requirements.txt에 포함되어 있습니다. logging은 Python의 표준 라이브러리로, 별도로 설치할 필요가 없습니다.
영향(버그/보안/성능/유지보수 등):
- 가독성/유지보수성: pip 설치 시 무시되므로 기능적 문제는 없지만, 불필요한 항목이 포함되어 있어 의존성 목록을 혼란스럽게 만듭니다.
제안(구체적 조치, 대안, 참고 링크는 선택):
requirements.txt 파일에서 logging 라인을 삭제하여 의존성 목록을 깔끔하게 유지하는 것이 좋습니다.

수정 제안 (requirements.txt):
```
- logging
prometheus-client==0.19.0
prometheus-fastapi-instrumentator==6.1.0
```

[P5] 메트릭 초기화 로직 분리 제안

파일/위치: app/main.py:14-15
근거(왜 문제인지): Prometheus Instrumentator를 초기화하고 적용하는 코드가 main.py의 최상위 레벨에 직접 작성되어 있습니다.
영향(버그/보안/성능/유지보수 등):
- 가독성: 현재는 코드가 짧아 문제가 없지만, 향후 미들웨어나 이벤트 핸들러 등 앱 초기화 로직이 복잡해지면 main.py 파일의 가독성이 떨어질 수 있습니다.

제안(구체적 조치, 대안, 참고 링크는 선택):
앱의 특정 기능을 설정하는 로직은 별도의 함수로 분리하면 구조가 더 명확해집니다. 예를 들어 setup_monitoring 같은 함수를 만들어 관리하는 것을 고려해볼 수 있습니다.

수정 제안 (app/main.py):

from fastapi import FastAPI
from app.core.lifespan import lifespan
from app.api.endpoints import predictions
from app.core.logging_config import setup_logging
from prometheus_fastapi_instrumentator import Instrumentator

def setup_monitoring(app: FastAPI):
    """Sets up the Prometheus instrumentator."""
    instrumentator = Instrumentator().instrument(app)
    instrumentator.expose(app, include_in_schema=False, endpoint="/actuator/prometheus")

setup_logging()
app = FastAPI(
    title="My App",
    description="FastAPI App",
    version="1.0.0",
    lifespan=lifespan
)

setup_monitoring(app)
app.include_router(predictions.router, prefix="/api/v1", tags=["Prediction"])

@app.get("/health")
# ...

전반적으로 모니터링 환경을 도입하여 시스템의 안정성과 관측 가능성을 크게 높이는 중요한 PR이라고 생각합니다. 몇 가지 제안 사항을 반영하면 더 견고하고 유지보수하기 좋은 구조가 될 것 같습니다. 수고하셨습니다! 👍

gemini-code-assist

Code Review

이 PR은 Prometheus와 Grafana를 사용하여 모니터링 환경을 추가하는 것을 목표로 합니다. FastAPI 애플리케이션에 메트릭 엔드포인트를 추가하고, 모니터링 스택을 위한 Docker Compose 설정 및 Prometheus 설정 파일을 추가했습니다. 전반적으로 좋은 방향이지만, Docker 네트워킹 설정 오류로 인해 모니터링이 정상적으로 동작하지 않을 수 있으며, Docker 이미지 태그와 볼륨 설정에 개선이 필요합니다. 아래에 자세한 리뷰 의견을 남겼습니다.

gemini-code-assist · 2025-10-02T07:45:14Z

+  - job_name: 'fastapi-actuator-blue'
+    metrics_path: '/actuator/prometheus'
+    scrape_interval: 1m
+    static_configs:
+      - targets: [ 'app-blue:8000' ]
+  - job_name: 'fastapi-actuator-green'
+    metrics_path: '/actuator/prometheus'
+    scrape_interval: 1m
+    static_configs:
+      - targets: [ 'app-green:8001' ]


fastapi-actuator-blue와 fastapi-actuator-green job이 app-blue:8000, app-green:8001을 타겟으로 하고 있습니다. 하지만 docker-compose.monitoring.yml과 docker-compose.yml이 별도의 파일로 관리되고 있어, Prometheus 컨테이너와 애플리케이션 컨테이너들이 서로 다른 Docker 네트워크에 속하게 될 가능성이 높습니다. 이 경우 Prometheus가 애플리케이션의 메트릭을 수집할 수 없습니다. 모든 컨테이너가 동일한 Docker 네트워크에 있도록 docker-compose.yml과 docker-compose.monitoring.yml의 네트워크 설정을 맞춰주어야 합니다. 예를 들어, 공통 외부 네트워크(external network)를 사용하도록 설정할 수 있습니다.

gemini-code-assist · 2025-10-02T07:45:14Z

+services:
+  prometheus:
+    user: ${PROMETHEUS_USER}
+    image: prom/prometheus:latest


prom/prometheus:latest와 같이 :latest 태그를 사용하는 것은 프로덕션 환경에서 예기치 않은 버전 변경으로 인한 문제를 일으킬 수 있습니다. 안정적인 운영을 위해 특정 버전(예: v2.51.2)을 명시하는 것이 좋습니다.

image: prom/prometheus:v2.51.2

gemini-code-assist · 2025-10-02T07:45:14Z

+
+  grafana:
+    user: ${GRAFANA_USER}
+    image: grafana/grafana:latest


grafana/grafana:latest와 같이 :latest 태그를 사용하는 것은 프로덕션 환경에서 예기치 않은 버전 변경으로 인한 문제를 일으킬 수 있습니다. 안정적인 운영을 위해 특정 버전(예: 11.0.0)을 명시하는 것이 좋습니다.

image: grafana/grafana:11.0.0

gemini-code-assist · 2025-10-02T07:45:14Z

+  - job_name: 'node'
+    static_configs:
+      - targets: ['${REMOTE_HOST}:9090']


node job의 targets가 Prometheus 자신을 가리키는 '${REMOTE_HOST}:9090'으로 설정되어 있습니다. node라는 이름으로 보아 Node Exporter 메트릭을 수집하려는 의도로 보이지만, 포트가 잘못되었습니다. Node Exporter는 보통 9100 포트를 사용합니다. 만약 Node Exporter를 사용하지 않는다면 이 job은 불필요하게 Prometheus 메트릭을 중복 수집하므로 제거하는 것이 좋습니다.

- job_name: 'node' static_configs: - targets: ['${REMOTE_HOST}:9100']

gemini-code-assist · 2025-10-02T07:45:14Z

+      - /home/ubuntu/dearbelly/deployment/prometheus.yml:/etc/prometheus/prometheus.yml:ro
+      - /home/ubuntu/prometheus/volume:/prometheus/data


Prometheus 볼륨 경로가 /home/ubuntu/...와 같이 절대 경로로 하드코딩되어 있어 다른 환경에서의 재사용성 및 이식성이 떨어집니다. 설정 파일은 상대 경로 (./prometheus.yml)를 사용하고, 데이터 볼륨은 Docker의 named volume을 사용하는 것을 권장합니다. 파일 하단에 volumes 섹션을 추가하여 prometheus-data named volume을 정의해야 합니다.

- ./prometheus.yml:/etc/prometheus/prometheus.yml:ro - prometheus-data:/prometheus/data

gemini-code-assist · 2025-10-02T07:45:14Z

+    ports:
+      - 3000:3000
+    volumes:
+      - /home/ubuntu/grafana/volume:/var/lib/grafana


Grafana 데이터 볼륨 경로가 /home/ubuntu/grafana/volume와 같이 절대 경로로 하드코딩되어 있어 이식성이 떨어집니다. Docker의 named volume을 사용하여 관리하는 것을 권장합니다. 파일 하단에 volumes 섹션을 추가하여 grafana-data named volume을 정의해야 합니다.

- grafana-data:/var/lib/grafana

youyeon11 and others added 6 commits October 2, 2025 15:53

fix: docker 명령어 파일 참조로 변경

ab92c09

feat: 모니터링 환경 추가(prometheus/grafana)

9708ad0

feat: 메트릭 데이터 path 설정

0da15a1

fix: transfer 경로 오타 수정

8aebacf

chore: prometheus 라이브러리 추가

cd73df1

Merge pull request #30 from DearBelly/feat/add-monitoring-29

e1abee9

[FEATURE] Prometheus/Grafana 환경 추가

gemini-code-assist Bot reviewed Oct 2, 2025

View reviewed changes

youyeon11 merged commit 797f3b9 into main Oct 2, 2025
1 check passed

Navigation Menu

Uh oh!

DEPLOY - v1.0.2 - #31

DEPLOY - v1.0.2#31
youyeon11 merged 6 commits into
mainfrom
develop

youyeon11 commented Oct 2, 2025

Uh oh!

gemini-code-assist Bot commented Oct 2, 2025

Uh oh!

youyeon11 commented Oct 2, 2025

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Oct 2, 2025

Uh oh!

gemini-code-assist Bot Oct 2, 2025

Uh oh!

gemini-code-assist Bot Oct 2, 2025

Uh oh!

gemini-code-assist Bot Oct 2, 2025

Uh oh!

gemini-code-assist Bot Oct 2, 2025

Uh oh!

gemini-code-assist Bot Oct 2, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		- /home/ubuntu/dearbelly/deployment/prometheus.yml:/etc/prometheus/prometheus.yml:ro
		- /home/ubuntu/prometheus/volume:/prometheus/data

Uh oh!

Conversation

youyeon11 commented Oct 2, 2025

📌 작업 목적

🗂 작업 유형

🔨 주요 작업 내용

📎 관련 이슈

Uh oh!

gemini-code-assist Bot commented Oct 2, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

youyeon11 commented Oct 2, 2025

🤖 Gemini 코드 리뷰 결과

1) PR 의도 요약

2) 전반적 평가 (품질/가독성/테스트/아키텍처)

3) 우선순위별 피드백 목록

[P2] 하드코딩된 경로를 사용하여 이식성 및 유지보수성 저하

[P2] 모니터링 스택 배포 자동화 누락

[P3] 환경 변수 설정에 대한 설명 부족

[P3] API 메트릭 수집 주기 과다

[P4] 불필요한 의존성 포함

[P5] 메트릭 초기화 로직 분리 제안

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant