Ch9. 관측 전략
API·Prisma·DB 세 레이어 지표와 OTel 트레이스, slow query 로깅, 배포 직후 강화 관측, SLO/에러버짓 기반 알림 설계를 다룹니다.
핵심 요약
- 관측을 애플리케이션(요청 실패율·응답시간)·Prisma(쿼리 지연·에러 코드)·DB(연결·락·복제 지연) 세 레이어로 나눠 봅니다.
- 2026-03-23
@prisma/extension-optimize지원이 종료되어withOptimize()를 제거하고 Prisma Postgres Query Insights로 전환합니다. - HTTP·서비스·DB 쿼리 span을 같은 trace id로 묶으면 OTel로 장애 원인을 추적하는 시간이 크게 줄어듭니다.
- slow query를 로깅할 땐 SQL/파라미터 마스킹 정책을 같이 두어 민감정보가 새지 않게 막습니다.
- 배포 후 30~60분은 error rate·slow query 임계치를 임시 하향하고, 에러버짓 25% 초과 시 신규 스키마 변경을 동결합니다.
관측은 세 레이어로 본다
- 애플리케이션: 요청 실패율, 응답 시간, 처리량
- Prisma: 쿼리 지연, 타임아웃, 에러 유형
- DB: 연결 수, 락 대기, 복제 지연, 디스크/CPU
필수 운영 지표
| 영역 | 지표 | 용도 |
|---|---|---|
| API | p95/p99 latency, error rate | 사용자 체감 영향 감지 |
| Prisma | 쿼리 지연 분포, Prisma 에러 코드 | ORM 계층 이상 탐지 |
| DB | active connections, lock wait, deadlock | 데이터 계층 병목 진단 |
| 복제 | replication lag | 읽기 일관성 위험 감지 |
| 배포 | migration duration, failed migration count | 변경 실패 조기 감지 |
Prisma Optimize 서비스 종료와 대체 경로
2026-03-23: Prisma Optimize 지원 중단
@prisma/extension-optimize 클라이언트 확장의 공식 지원이 끝났습니다.
그동안 withOptimize()를 쓰던 프로젝트는 아래 조치를 진행하세요.
필수 조치:
- PrismaClient 초기화에서
withOptimize()확장 호출을 제거 @prisma/extension-optimize패키지를devDependencies/dependencies에서 삭제- Prisma Postgres의 Query Insights(아래 참고)로 쿼리 성능 분석을 전환
Optimize 확장을 제거한 뒤 아래의 Prisma 7 adapter 기반 factory로 초기화합니다. 과거의 adapter 없는 new PrismaClient() 예제를 현재 초기화 코드로 복사하지 않습니다.
Prisma Postgres Query Insights
Prisma Postgres는 Query Insights 대시보드를 기본으로 제공합니다. Prisma Optimize의 후속 대안으로, 느린 쿼리와 빈번한 쿼리, 에러 패턴을 콘솔에서 한눈에 확인합니다. 별도 APM을 붙이기 전에도 기본 수준의 쿼리 성능은 모니터링할 수 있습니다.
운영 권장:
- Query Insights로 상위 느린 쿼리 주간 리뷰
- v7.5.0 향상된 Prisma Studio에서 raw SQL 실행으로 즉석 진단 가능
- 상세 분석은 OTel 트레이싱과 병행
Prisma Studio v7.5.0 향상 기능
v7.5.0에서 Prisma Studio가 크게 개선되어 운영 진단 도구로 쓰기 좋아졌습니다.
- 다중 셀 선택: 여러 셀을 한 번에 선택·복사해 데이터를 비교하기 쉬움
- SQL 필터: 테이블 뷰에서 SQL 조건식으로 직접 필터링 — 복잡한 조건 조회 가능
- Cmd+K 팔레트: 명령 팔레트로 테이블 탐색, 필터, 작업을 키보드만으로 빠르게 수행
Prisma 쿼리 로깅 예시
다음 factory를 프로세스별 singleton 초기화 안에서 한 번 호출합니다. 요청마다 새 client를 만들거나 HMR 때마다 같은 client에 listener를 추가하지 않습니다.
import { PrismaClient } from '../generated/prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'
export function createObservedPrisma(connectionString: string) {
const prisma = new PrismaClient({
adapter: new PrismaPg({ connectionString, max: 10 }),
log: [{ emit: 'event', level: 'query' }, 'warn', 'error'],
})
prisma.$on('query', event => {
if (event.duration > 500) {
console.warn(JSON.stringify({
event: 'slow_query',
duration_ms: event.duration,
target: event.target,
}))
}
})
return prisma
}이 예제는 query 본문·params를 기본 출력하지 않습니다. SQL 문자열 자체에도 개인정보가 들어갈 수 있으므로 “params만 지우면 안전”으로 해석하지 않습니다. 500ms와 pool 10은 팀 정책 예시입니다. 실제 span·metric·Query Insights를 함께 대조합니다.
트레이싱(OTel) 권장 구조
- HTTP request span
- service/business span
- DB query span (Prisma/driver)
세 레이어를 같은 trace id로 묶으면 장애가 났을 때 원인을 추적하는 시간이 크게 줄어듭니다.
알림 설계 원칙
- 페이지 알림(Pager): 사용자 영향 지표 위주
- 채널 알림(ChatOps): 경고/추세 이상
- 대시보드: 탐색용, 알림 대체 수단으로 사용하지 않음
배포 직후 강화 관측
배포 30~60분은 임시 룰을 적용합니다.
- error rate 임계치 하향
- slow query 임계치 하향
- migration 관련 로그 키워드 필터 활성화
SLO 기반 운영 예시
SLO: 결제 API 성공률 99.95% (30일)
Error Budget 소진율이 25%를 초과하면:
- 신규 스키마 변경 동결
- 성능/안정성 개선 작업 우선