Next.js OpenTelemetry 관측 가능성 스킬 (nextjs-otel)
Next.js App Router 애플리케이션에서 OpenTelemetry 추적을 구성, 테스트 및 검증하기 위한 모듈식 프로덕션 준비 워크플로우입니다. 단일 킬 스위치를 표준화하고, @vercel/otel 초기화 버그로부터 보호하며, 추적 검증을 자동화합니다.
워크플로우 개요
flowchart TD
A["1. 프로젝트 평가<br/>(App Router 및 package.json)"] --> B["2. 의존성 설치<br/>(@vercel/otel 및 @opentelemetry/api)"]
B --> C["3. instrumentation.ts 배포<br/>(registerOTel + onRequestError)"]
C --> D["4. 환경 구성<br/>(.env.example 및 .env.local)"]
D --> E["5. 검증 및 테스트<br/>(모의 수집기 및 킬 스위치)"]
단계별 실행 런북
OpenTelemetry 관측 가능성을 구성하고 검증하려면 다음 체크리스트를 순서대로 따르세요:
1. 프로젝트 발견 및 의존성 검사
- 프로젝트 구조 검사:
package.json에서 Next.js App Router 버전과 패키지 매니저(pnpm,bun,npm)를 확인합니다. - 계측 루트 찾기: 프로젝트가 루트
instrumentation.ts또는src/instrumentation.ts를 사용하는지 확인합니다. - 아키텍처 표준 검토: 단일 킬 스위치 규율 및 런타임 경계에 대해 architectural-standards.md를 참조합니다.
2. 의존성 설치
- 핵심 텔레메트리 패키지 설치:
pnpm add @vercel/otel @opentelemetry/api
3. instrumentation.ts 배포
- 계측 파일 생성: instrumentation.ts.template을 루트 또는
src/에 배포합니다. - Truthiness 보호 장치 적용:
@vercel/otel의 boolean 평가 버그를 피하기 위해register()가OTEL_SDK_DISABLED가 엄격하게"true"가 아닐 때process.env.OTEL_SDK_DISABLED를 삭제하는지 확인합니다. - 오류 추적 연결:
onRequestError()가 활성 스팬에next.error.digest, 경로, HTTP 메타데이터를 캡처하는지 확인합니다.
4. 환경 변수 구성
- 환경 템플릿 업데이트: env.otel.template을 사용하여
.env.example및.env.local에 OpenTelemetry 구성을 추가합니다. - 서비스 이름 및 프로토콜 설정:
OTEL_SERVICE_NAME,OTEL_EXPORTER_OTLP_ENDPOINT,OTEL_EXPORTER_OTLP_PROTOCOL=http/json을 구성합니다.
5. 검증 및 테스트
- 모의 OTLP 수집기 시작: verification-and-testing.md에 따라 포트 4318에서 테스트 수집기를 시작합니다:
node .agents/skills/nextjs-otel/scripts/mock_collector.js - 활성 추적 확인 (
OTEL_SDK_DISABLED=false): 테스트 요청 (curl http://localhost:3000/)을 트리거하고POST /v1/traces배치가 HTTP 200 OK를 반환하는지 확인합니다. - 킬 스위치 확인 (
OTEL_SDK_DISABLED=true): Next.js 서버 로그에[OTel] Instrumentation hook skipped가 출력되고 0개의 추적이 전송되는지 확인합니다. - 검증 보고서 출력: Markdown 요약 보고서를 생성합니다.
엣지 케이스 및 알려진 AI 함정
[!WARNING]
@vercel/otel문자열 Truthiness 버그:@vercel/otel은!!process.env.OTEL_SDK_DISABLED를 평가합니다. JavaScript에서Boolean("false")는true입니다.OTEL_SDK_DISABLED가'true'가 아닐 때 이를 삭제하지 않으면OTEL_SDK_DISABLED=false로 설정해도 추적이 자동으로 비활성화되지 않습니다.- 보조 사용자 정의 플래그:
OTEL_SDK_DISABLED와 함께OTEL_ENABLED를 절대 도입하지 마십시오.OTEL_SDK_DISABLED를 엄격하게 표준화하십시오.- 런타임 경계 위반:
instrumentation.ts나 서버 OpenTelemetry SDK를 클라이언트 컴포넌트("use client")로 가져오지 마십시오.- 명령 체이닝: 명령을 체이닝(
&&,||,;)하지 마십시오. 모든 설정 및 테스트 명령은 개별적으로 실행하십시오.
출력 요약 스키마
OpenTelemetry 설정 또는 검증을 완료한 후 구조화된 보고서를 출력합니다:
# OpenTelemetry 검증 보고서
## 상태 요약
- **OTel 상태**: 활성 / 비활성화
- **서비스 이름**: <구성된_서비스_이름>
- **대상 엔드포인트**: <구성된_엔드포인트>
- **내보내기 프로토콜**: http/json | http/protobuf
## 검증 결과
| 검사 | 예상 | 실제 | 상태 |
| :-------------------------- | :-------------------------- | :------------------ | :--- |
| 초기화 훅 | 등록됨 | 등록됨 | PASS |
| 추적 전송 (활성) | POST /v1/traces (200 OK) | X개 배치 수신 | PASS |
| 킬 스위치 (비활성화) | 건너뜀, 0개 추적 | 건너뜀, 0개 추적 | PASS |
| 유형 검사 | 0개 오류 | 0개 오류 | PASS |
참조 가이드 및 템플릿
- 아키텍처 표준 참조 — 킬 스위치 규율, truthiness 버그 메커니즘 및 오류 컨텍스트.
- 검증 및 테스트 런북 — 테스트 도구 지침, curl 트리거 및 킬 스위치 검증.
- 계측 템플릿 — 오류 처리를 포함한 완전한
instrumentation.ts. - 환경 구성 템플릿 — 완전한
.env구성 키. - 모의 수집기 스크립트 — 경량 Node.js OTLP HTTP 수집기 도구.