프론트엔드 운영 모니터링: 로그·알림·롤백·장애 대응

관측 가능한 배포 만들기

운영에서 가장 곤란한 상태는 문제가 발생했는데 어떤 코드가 실행 중인지 모르는 경우입니다.

최소한 다음 정보를 연결할 수 있어야 합니다.

Production URL
↓
Deployment
↓
Commit SHA
↓
Build log
↓
Runtime log

배포마다 모든 로그를 별도 문서에 복사할 필요는 없습니다.

대신 어떤 deployment와 commit이 운영 중인지 식별할 수 있는 기준을 남깁니다.

build log와 runtime log

Vercel의 운영 흐름에서도 build 단계 문제와 배포 후 runtime 문제는 분리해서 확인할 수 있습니다.

build log

다음과 같은 문제를 찾을 때 사용합니다.

npm ci 실패
TypeScript 오류
build command 실패
환경변수 누락
page generation 실패

runtime log

deployment가 만들어진 뒤 실제 요청 처리 중 발생하는 문제를 찾을 때 사용합니다.

Route Handler 오류
server-side API 호출 실패
DB 연결 실패
예외 throw
500 응답

build가 성공했다는 이유로 runtime log를 확인하지 않으면 운영 중에만 발생하는 문제를 놓칠 수 있습니다.

최소 모니터링 항목

작은 개인 프로젝트라도 다음 정도는 확인할 수 있으면 좋습니다.

1. 홈페이지가 응답하는가
2. 핵심 사용자 route가 응답하는가
3. 주요 API가 예상 상태를 반환하는가
4. 5xx가 증가하지 않는가
5. 인증 흐름이 정상인가
6. 현재 Production deployment가 무엇인가

단순 uptime 체크만으로 전체 서비스 정상 여부를 보장할 수는 없습니다.

GET /
→ 200

하지만
POST /api/tasks
→ 500

홈페이지가 열리더라도 핵심 기능은 실패할 수 있습니다.

알림 기준

알림은 많을수록 좋은 것이 아닙니다.

무조건 모든 404를 장애 알림으로 보내면 봇이나 잘못된 URL 때문에 실제 문제를 놓칠 수 있습니다.

다음처럼 사용자 영향이 큰 조건을 우선합니다.

지속적인 5xx
핵심 API 실패
로그인 실패율 증가
홈페이지/핵심 route 응답 실패
배포 직후 오류 증가

서비스 규모에 따라 응답시간, 오류율, 트래픽, 외부 API 실패 등을 확장할 수 있습니다.

rollback

운영에 문제가 생겼을 때 항상 새 코드를 수정해 다시 build할 필요는 없습니다.

플랫폼이 이전 deployment로 트래픽을 되돌리는 기능을 제공한다면 빠른 복구 수단으로 사용할 수 있습니다.

Vercel은 이전 Production deployment를 대상으로 rollback할 수 있습니다. Hobby는 바로 이전 배포, Pro·Enterprise는 자격을 갖춘 이전 배포를 선택할 수 있으므로 실제 대상과 권한을 먼저 확인합니다. 롤백 후에는 Production 도메인 자동 할당이 꺼져 새 push가 자동 공개되지 않습니다. 정상 배포를 승격하거나 Undo Rollback을 완료한 뒤 자동 할당 재개 여부까지 확인합니다.

개념적으로는 다음과 같습니다.

Deployment A
정상

Deployment B
문제 발생

Traffic
B → A로 되돌림

이것은 Git revert와 같은 작업이 아닙니다.

Rollback
→ 운영 트래픽이 가리키는 deployment 변경

Git revert
→ 저장소에 이전 변경을 되돌리는 새 commit 생성

운영 복구를 먼저 하고 원인을 수정한 새 commit을 만들 수도 있습니다.

rollback 후에도 확인할 것이 있습니다

이전 버전으로 되돌렸다고 모든 문제가 해결된 것은 아닙니다.

특히 다음 항목은 별도로 확인해야 합니다.

DB schema가 새 버전에서 변경되었는가
환경변수가 변경되었는가
외부 API 설정이 바뀌었는가
캐시가 새 버전 응답을 가지고 있는가
사용자 데이터가 이미 변경되었는가

프론트엔드 deployment rollback만으로 데이터 변경까지 자동 복구된다고 가정하면 안 됩니다.

incident 기록

장애가 끝난 뒤 기억에 의존하지 않도록 작은 기록을 남깁니다.

# Incident

## Summary
무슨 문제가 발생했는가

## Started
언제 처음 확인했는가

## Impact
어떤 사용자 기능에 영향이 있었는가

## Detection
어떻게 발견했는가

## Root cause
확인된 원인은 무엇인가

## Recovery
어떤 조치로 복구했는가

## Verification
복구 후 무엇을 다시 확인했는가

## Prevention
같은 문제를 줄이기 위해 무엇을 바꿀 것인가

원인이 확인되지 않았다면 추측을 root cause로 확정해서 쓰지 않습니다.

장애 대응 순서

실제 장애에서는 다음 순서를 기준으로 삼을 수 있습니다.

1. 영향 확인
2. 현재 deployment와 commit 기록
3. 증상·status·log 수집
4. build/runtime/network 계층 분류
5. 빠른 안전 복구가 필요하면 rollback
6. 원인 수정
7. 새 deployment 검증
8. 핵심 기능 회귀 확인
9. incident 기록

사용자 영향이 큰 상황에서는 원인 분석을 완벽히 끝낼 때까지 장애 상태를 유지하는 것보다 안전한 복구를 먼저 선택할 수도 있습니다.

학습 완료 체크리스트

• build log와 runtime log 차이를 설명할 수 있습니다.
• Production deployment와 commit을 연결할 수 있습니다.
• 단순 uptime과 핵심 기능 정상 여부를 구분할 수 있습니다.
• rollback과 Git revert 차이를 이해했습니다.
• rollback 후 추가 검증이 필요한 이유를 설명할 수 있습니다.
• incident 기록에 사실과 추측을 구분할 수 있습니다.

# Incident


## Summary


## Started


## Impact


## Evidence


## Root cause


## Recovery


## Verification


## Prevention

# TaskFlow Rollback Runbook


## Before rollback
1. 현재 deployment 기록
2. 현재 commit 기록
3. 사용자 영향 확인
4. 로그와 status 확보


## Rollback
- 이전 정상 deployment를 선택
- 운영 트래픽을 정상 버전으로 전환


## After rollback
1. 홈페이지 확인
2. 핵심 route 확인
3. 주요 API 확인
4. 인증 흐름 확인
5. 환경변수·외부 서비스 영향 확인

6. Vercel Instant Rollback 후 Production 도메인 자동 할당 상태를 확인한다. 정상 deployment를 승격하거나 Undo Rollback으로 자동 배포를 재개한다.

# TaskFlow Rollback Runbook

## Before rollback
1. 현재 deployment 기록
2. 현재 commit 기록
3. 사용자 영향 확인
4. 로그와 status 확보

## Rollback
- 이전 정상 deployment를 선택
- 운영 트래픽을 정상 버전으로 전환

## After rollback
1. 홈페이지 확인
2. 핵심 route 확인
3. 주요 API 확인
4. 인증 흐름 확인
5. 환경변수·외부 서비스 영향 확인
6. Production 도메인 자동 할당 상태 확인; 정상 배포 승격/Undo Rollback으로 재개

# Incident

## Summary

## Started

## Impact

## Evidence

## Root cause

## Recovery

## Verification

## Prevention

# 7편 NEXT_PUBLIC_API_URL을 이 회차부터 NEXT_PUBLIC_API_BASE_URL로 통일합니다.
# 끝에 /가 없는 API origin을 설정하세요. 공개 API 주소만 넣고 secret은 넣지 마세요.
NEXT_PUBLIC_API_BASE_URL=
API_SECRET=

name: CI


on:
  push:
    branches:
      - main
  pull_request:


jobs:
  build:
    runs-on: ubuntu-latest


    steps:
      - name: Checkout
        uses: actions/checkout@v7


      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: "24.x"
          cache: "npm"


      - name: Install dependencies
        run: npm ci


      - name: Build
        run: npm run build

node_modules/
.next/
.env.local
*.tsbuildinfo

24

import type { ReactNode } from "react";
export default function RootLayout({ children }: { children: ReactNode }) {
  return <html lang="ko"><body>{children}</body></html>;
}

import Link from "next/link";
export default function Home() {
  return <main><h1>TaskFlow 배포 진단 실습</h1><Link href="/tasks">작업 목록</Link></main>;
}

export default function TasksPage() {
  return (
    <main>
      <h1>Tasks</h1>
      <p>TaskFlow 작업 목록입니다.</p>
    </main>
  );
}

# TaskFlow Deployment Plan


## Build
- package manager: npm
- install: npm ci
- build: npm run build


## Primary deployment
- platform: Vercel
- environment: Production


## Alternative deployment
- Firebase Hosting: static output일 때 검토
- Firebase App Hosting: server runtime이 필요할 때 검토


## Verification
- Production URL 응답
- 주요 화면 확인
- 환경변수 확인
- 주요 route 확인
- 현재 commit 확인
- rollback 가능 여부 확인

## Runtime decision


- static-only: no
- server runtime required: yes
- reasons:
  - Route Handler
  - server-side environment variables


## Primary
Vercel Production


## Firebase alternative
App Hosting 우선 검토


## Static variant
정적 결과물로 분리할 경우 Firebase Hosting 검토

## Production deployment


- deployment URL: 운영 문서에서 관리
- commit SHA: 배포마다 기록
- deployment status: 확인
- build log: 확인
- smoke test: 확인

## Domain


- canonical domain: 운영 문서에서 관리
- www policy: canonical로 redirect
- HTTPS: 확인
- DNS status: 확인
- auth callback / allowed origin: 확인

## Runtime difference checklist


1. Production deployment와 commit 확인
2. 환경변수 이름·scope 확인
3. Request URL과 status 확인
4. Response headers 확인
5. origin / proxy 경로 확인
6. cache 여부 확인
7. 수정 후 새 deployment에서 재검증

# Incident


## Summary


## Started


## Impact


## Evidence


## Root cause


## Recovery


## Verification


## Prevention

# TaskFlow Rollback Runbook


## Before rollback
1. 현재 deployment 기록
2. 현재 commit 기록
3. 사용자 영향 확인
4. 로그와 status 확보


## Rollback
- 이전 정상 deployment를 선택
- 운영 트래픽을 정상 버전으로 전환


## After rollback
1. 홈페이지 확인
2. 핵심 route 확인
3. 주요 API 확인
4. 인증 흐름 확인
5. 환경변수·외부 서비스 영향 확인

6. Vercel Instant Rollback 후 Production 도메인 자동 할당 상태를 확인한다. 정상 deployment를 승격하거나 Undo Rollback으로 자동 배포를 재개한다.

# Server Access Runbook


## Connection
- host: 저장하지 않음
- user: 환경별 문서에서 별도 관리
- authentication: SSH key 우선
- private key: 저장소에 포함 금지


## Before upload
1. 대상 서버 확인
2. 현재 경로 확인
3. 배포 대상 경로 확인
4. 기존 파일 상태 확인


## After upload
1. 파일 존재 확인
2. owner / permission 확인
3. 서비스가 실제 경로를 읽는지 확인
4. HTTP 결과 확인


## Never commit
- private key
- password
- access token
- production secret

/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/types/routes.d.ts";
import "./.next/types/root-params.d.ts";

// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

import type { NextConfig } from "next";


const nextConfig: NextConfig = {
  async rewrites() {
    return [
      {
        source: "/legacy/tasks",
        destination: "/tasks",
      },
    ];
  },
};


export default nextConfig;

{
  "name": "taskflow-deployment-lab",
  "private": true,
  "engines": {
    "node": "24.x"
  },
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "next": "16.3.5",
    "react": "19.3.0",
    "react-dom": "19.3.0"
  },
  "devDependencies": {
    "typescript": "5.9.3",
    "@types/node": "24.10.1",
    "@types/react": "19.2.7",
    "@types/react-dom": "19.2.3"
  }
}

# 배포·서버 10 — deploy-step-10-observability-rollback

이 ZIP은 8편의 /legacy/tasks → /tasks rewrite를 재현하는 최소 Next.js 앱과 이전 회차 운영 문서를 포함합니다. 기존 TaskFlow 전체 기능, 로그인, 실제 API 서버나 Production 배포 상태를 제공하지 않습니다.

Node.js 24.x, npm을 사용합니다. `npm ci` → `npm run typecheck` → `npm run build`로 확인하고 `npm run dev` 후 `/tasks`, `/legacy/tasks`를 비교합니다. 전체 의존성 잠금 파일은 package-lock.json에 있습니다.

.env.example은 값이 빈 설정 안내입니다. 독자의 앱에서 사용하는 변수만 .env.local 또는 플랫폼의 해당 환경에 설정하세요. URL·계정·비밀키를 ZIP에 넣지 않습니다.

CI workflow는 이미 package.json/package-lock.json과 build 스크립트가 있는 기존 npm 프로젝트 루트에 적용합니다. actions/checkout@v7, actions/setup-node@v7, Node 24.x를 사용합니다. GitHub 원격 실행은 검증하지 않았습니다.

src/lib/env.ts는 해당 모듈을 import할 때 환경 변수를 검사합니다. 파일을 추가하기만 해서는 사용하지 않는 앱 전체의 환경 설정이 자동 검증되지 않습니다.

9편부터 변수명을 NEXT_PUBLIC_API_BASE_URL로 통일합니다. 7편 NEXT_PUBLIC_API_URL 값의 이름을 바꾸고 Preview/Production scope에도 반영한 뒤 다시 build해야 합니다. 끝에 /가 없는 API origin을 입력하세요. src/lib/api.ts의 getTasks는 독자의 실제 /api/tasks API를 호출하는 함수이며 이 최소 앱에는 API 서버와 호출 UI를 추가하지 않았습니다.

이 자료에는 실제 배포·DNS 변경·SSH 접속·메일/알림·롤백 결과가 없습니다. 운영 작업은 독자가 본인 환경과 권한을 확인한 후 수행해야 합니다. 문서의 확인 항목은 수행할 체크리스트이며 이미 통과했다는 기록이 아닙니다.

import { env } from "./env";


export async function getTasks() {
  const response = await fetch(`${env.apiBaseUrl}/api/tasks`);


  if (!response.ok) {
    throw new Error(`Failed to fetch tasks: ${response.status}`);
  }


  return response.json();
}

function required(name: string, value: string | undefined) {
  if (!value) {
    throw new Error(`Missing environment variable: ${name}`);
  }


  return value;
}


export const env = {
  apiBaseUrl: required(
    "NEXT_PUBLIC_API_BASE_URL",
    process.env.NEXT_PUBLIC_API_BASE_URL,
  ),
};

{
  "compilerOptions": {
    "target": "ES2017",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "react-jsx",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": [
        "./*"
      ]
    }
  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    ".next/types/**/*.ts",
    ".next/dev/types/**/*.ts"
  ],
  "exclude": [
    "node_modules"
  ]
}

deploy-step-09-runtime-diff

docs/
├─ deployment-plan.md
├─ rollback-runbook.md
└─ incident-template.md

deploy-step-10-observability-rollback

다음 학습

마지막 글에서는 지금까지 배운 install, build, route, env, DNS, cache, runtime, rollback 문제를 하나의 장애 대응 체크리스트로 통합합니다.

다음 글: 프론트엔드 배포 오류 해결 허브

다음 회차 확인 과제: 11회차에서는 01~10회차의 증거 수집표·smoke test·롤백 기록을 하나의 장애 대응 순서로 연결합니다.

공식 문서

공식 문서 확인 기준: 2026-09-21

• https://vercel.com/docs/logs
• https://vercel.com/docs/deployments
• https://vercel.com/docs/instant-rollback
• https://vercel.com/docs/observability