기술 보고서 작성 가이드: 구조 설계부터 데이터 시각화, 자동화까지

# ADR-001: 메시지 큐 선택

## 상태

승인됨 (2026-03-10)

## 맥락

주문 처리 시스템에서 비동기 메시지 처리가 필요합니다.
현재 일일 주문량은 50만 건이며, 피크 시 초당 1,000건을 처리해야 합니다.

## 결정

Apache Kafka를 메시지 큐로 선택합니다.

## 근거

- 높은 처리량: 초당 수십만 건 처리 가능
- 내구성: 디스크 기반 저장으로 메시지 유실 방지
- 스트림 처리: Kafka Streams를 통한 실시간 처리 지원

## 대안 검토

- RabbitMQ: 처리량 제한 (초당 약 10,000건)
- Amazon SQS: 벤더 종속성 우려

## 결과

Kafka 클러스터 구축 및 운영을 위한 인프라 비용이 추가됩니다.
팀 내 Kafka 운영 경험이 필요하며, 학습 비용이 발생합니다.

성능 저하 원인
├── 인프라 계층
│   ├── CPU 병목
│   ├── 메모리 부족
│   ├── 디스크 I/O 과부하
│   └── 네트워크 지연
├── 애플리케이션 계층
│   ├── 비효율적 알고리즘
│   ├── 메모리 누수
│   ├── 스레드 경합
│   └── 커넥션 풀 고갈
└── 데이터 계층
    ├── 쿼리 비효율
    ├── 인덱스 누락
    ├── 테이블 잠금 경합
    └── 데이터 편향 (Skew)

# 프로젝트 상태 보고서

**프로젝트**: 결제 시스템 리팩토링
**보고 기간**: 2026-03-07 ~ 2026-03-13
**작성자**: 홍길동
**상태**: 정상 진행 (On Track)

## Executive Summary

결제 시스템 리팩토링 2단계가 예정대로 진행 중입니다.
이번 주 주요 성과로 레거시 API 마이그레이션 3건을 완료했으며,
다음 주에는 성능 테스트와 스테이징 배포를 진행할 예정입니다.

## 주요 진척 사항

| 마일스톤         | 예정일 | 상태    | 진척률 |
| ---------------- | ------ | ------- | ------ |
| API 마이그레이션 | 03-14  | 진행 중 | 75%    |
| 성능 테스트      | 03-21  | 예정    | 0%     |
| 스테이징 배포    | 03-25  | 예정    | 0%     |
| 프로덕션 배포    | 04-01  | 예정    | 0%     |

## 이번 주 완료 항목

- 결제 조회 API v2 마이그레이션 완료
- 환불 처리 API v2 마이그레이션 완료
- 정산 API v2 마이그레이션 완료

## 리스크 및 이슈

| 리스크             | 영향도 | 발생 가능성 | 대응 방안                    |
| ------------------ | ------ | ----------- | ---------------------------- |
| 외부 PG사 API 변경 | 높음   | 중간        | PG사와 사전 조율 완료        |
| 테스트 환경 불안정 | 중간   | 높음        | 전용 테스트 클러스터 구축 중 |

## 다음 주 계획

1. 잔여 API 마이그레이션 2건 완료
2. 통합 테스트 환경 구축
3. 성능 테스트 시나리오 작성

# 장애 보고서

**장애 ID**: INC-2026-0312-001
**심각도**: P1 (Critical)
**작성자**: 김철수
**작성일**: 2026-03-12

## 요약

2026년 3월 12일 14:23 ~ 15:47(KST), 결제 서비스가 약 84분간
전면 중단되었습니다. 전체 사용자 중 약 32만 명이 영향을 받았으며,
예상 매출 손실은 약 1.2억 원입니다.

## 타임라인

| 시각 (KST) | 이벤트                                  |
| ---------- | --------------------------------------- |
| 14:23      | 결제 성공률 알림 발생 (임계값 95% 이하) |
| 14:25      | 온콜 엔지니어 확인, 조사 시작           |
| 14:35      | DB 커넥션 풀 고갈 확인                  |
| 14:45      | 원인으로 신규 배포된 배치 작업 의심     |
| 15:02      | 배치 작업 중지, 커넥션 풀 수동 정리     |
| 15:30      | 결제 성공률 99% 이상 회복               |
| 15:47      | 정상 상태 확인, 장애 종료 선언          |

## 근본 원인 분석 (Root Cause Analysis)

신규 배포된 정산 배치 작업에서 트랜잭션 타임아웃 설정이 누락되어,
장시간 실행되는 쿼리가 DB 커넥션을 점유한 채 반환하지 않았습니다.
커넥션 풀(최대 100개)이 30분 내에 고갈되어 신규 결제 요청이
처리되지 못했습니다.

## 개선 조치

| 조치 항목                               | 담당자 | 기한  | 우선순위 |
| --------------------------------------- | ------ | ----- | -------- |
| 배치 작업 트랜잭션 타임아웃 설정        | 김철수 | 03-14 | P0       |
| 커넥션 풀 모니터링 알림 추가            | 박영희 | 03-17 | P1       |
| 배포 전 체크리스트에 타임아웃 검증 추가 | 이민수 | 03-21 | P1       |
| 커넥션 풀 사이즈 확대 검토              | 김철수 | 03-28 | P2       |

## 교훈

1. 배치 작업도 API와 동일한 수준의 타임아웃 정책을 적용해야 합니다
2. 리소스 풀 사용량에 대한 모니터링과 알림이 필수적입니다
3. 배포 체크리스트에 타임아웃/리소스 설정 검증을 포함해야 합니다

# 캐싱 솔루션 비교 분석

## Executive Summary

사용자 세션 캐싱 솔루션으로 Redis를 권장합니다.
Memcached 대비 데이터 구조 지원이 풍부하고,
Persistence 기능으로 장애 시 데이터 복구가 가능합니다.

## 비교 분석

| 기준             | Redis                          | Memcached         | 가중치 |
| ---------------- | ------------------------------ | ----------------- | ------ |
| 처리 성능 (TPS)  | 10만+                          | 12만+             | 20%    |
| 데이터 구조 지원 | 풍부 (String, Hash, List, Set) | 단순 (Key-Value)  | 25%    |
| Persistence      | 지원 (RDB, AOF)                | 미지원            | 20%    |
| 클러스터링       | 네이티브 지원                  | 클라이언트 사이드 | 15%    |
| 운영 편의성      | 높음                           | 보통              | 10%    |
| 커뮤니티/생태계  | 매우 활발                      | 활발              | 10%    |
| **종합 점수**    | **87/100**                     | **71/100**        | -      |

import pandas as pd
import matplotlib.pyplot as plt
from datetime import datetime, timedelta

# 주간 보고서 데이터 자동 수집
def generate_weekly_report(start_date, end_date):
    """주간 성능 보고서 자동 생성"""

    # 데이터 로드
    metrics = pd.read_csv("metrics.csv", parse_dates=["timestamp"])
    mask = (metrics["timestamp"] >= start_date) & (metrics["timestamp"] <= end_date)
    weekly_data = metrics[mask]

    # 주요 지표 계산
    summary = {
        "avg_response_time_ms": weekly_data["response_time"].mean(),
        "p99_response_time_ms": weekly_data["response_time"].quantile(0.99),
        "error_rate_pct": (weekly_data["status"] >= 500).mean() * 100,
        "total_requests": len(weekly_data),
        "uptime_pct": (1 - weekly_data["downtime_minutes"].sum() / (7 * 24 * 60)) * 100,
    }

    return summary

# 차트 생성
def create_trend_chart(data, metric_name, title):
    """시계열 추이 차트 생성"""
    fig, ax = plt.subplots(figsize=(10, 5))
    ax.plot(data["timestamp"], data[metric_name], linewidth=2)
    ax.set_title(title, fontsize=14, fontweight="bold")
    ax.set_xlabel("날짜")
    ax.set_ylabel(metric_name)
    ax.grid(True, alpha=0.3)
    plt.tight_layout()
    return fig

# .github/workflows/weekly-report.yml
name: Weekly Performance Report

on:
  schedule:
    - cron: '0 9 * * 1' # 매주 월요일 오전 9시

jobs:
  generate-report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Generate report
        run: python scripts/generate_weekly_report.py

      - name: Create PR with report
        run: |
          git checkout -b report/weekly-$(date +%Y-%m-%d)
          git add reports/
          git commit -m "Add weekly report for $(date +%Y-%m-%d)"
          gh pr create --title "Weekly Report $(date +%Y-%m-%d)" --body "Auto-generated weekly performance report"