기존 Next.js 라우트 하나 관측하기

기존 Next.js App Router 앱에서 최신 패치가 적용된 현재 버전과 지원되는 Node.js 배포 환경을 사용하세요. after API는 Next.js 15.1부터 안정 버전이지만, 이 API 최소 버전은 패치되지 않은 오래된 버전을 권장한다는 뜻이 아닙니다. 핸들러가 Response를 반환하거나 예외를 던진 상황을 관측합니다. 브라우저 도착, 스트리밍 본문의 완료, 백그라운드 업무 완료는 측정하지 않습니다.

라우트를 변경하기 전에

직접 관리하는 라우트와 안전하게 실행할 수 있는 승인된 작업을 선택합니다. 인증, 검증, 업무 로직은 유지합니다. TELEMETRY_API_KEY는 서버 환경에만 두고 NEXT_PUBLIC_ 접두사를 사용하지 않습니다. 홈페이지의 익명 키는 전송과 조회를 지원합니다. 계정 키로 검증하려면 read-and-write 권한이 필요합니다. 전송만 하는 앱에는 수집 전용 키를 사용할 수 있습니다.

서버 도우미 추가

lib/with-telemetry.js로 저장합니다. 고객 식별자가 없는 고정 라우트 템플릿을 사용합니다. 생성된 ID는 핸들러 호출 한 번을 나타내며 사람이나 논리 작업을 나타내지 않습니다. URL, 본문, 쿠키, 헤더, 오류 메시지는 전송하지 않습니다.

import { after } from 'next/server';
import { randomUUID } from 'node:crypto';

function warnTelemetry(message) {
  try {
    console.warn(message);
  } catch {
    // Diagnostic failure must not change the application outcome.
  }
}

export function withTelemetry(handler, routeTemplate) {
  return async function observedHandler(request, context) {
    const started = performance.now();
    const invocationId = randomUUID();
    let outcome = 'threw';
    let statusCode = null;
    try {
      const response = await handler(request, context);
      outcome = 'returned_response';
      statusCode = response.status;
      return response;
    } finally {
      const event = {
        invocation_id: invocationId,
        route_template: routeTemplate,
        method: request.method,
        handler_outcome: outcome,
        status_code: statusCode,
        latency_ms: performance.now() - started,
        environment: process.env.NODE_ENV || 'development',
      };
      try {
        after(async () => {
          const key = process.env.TELEMETRY_API_KEY;
          if (!key) {
            warnTelemetry('Telemetry key missing; event not sent');
            return;
          }
          try {
            const response = await fetch('https://api.telemetry.sh/log', {
              method: 'POST',
              headers: {
                Authorization: `Bearer ${key}`,
                'Content-Type': 'application/json',
              },
              cache: 'no-store',
              signal: AbortSignal.timeout(2000),
              body: JSON.stringify({ table: 'nextjs_route_observed', data: event }),
            });
            if (!response.ok) warnTelemetry('Telemetry event send rejected');
          } catch {
            warnTelemetry('Telemetry event send failed');
          }
        });
      } catch {
        warnTelemetry('Telemetry background scheduling failed');
      }
    }
  };
}

기존 핸들러 감싸기

기존에 내보내는 GET 함수 이름을 existingGET로 바꾸되 함수 내용은 유지합니다. 그런 다음 아래 래퍼를 내보냅니다. 메서드와 고정 템플릿은 실제 라우트에 맞춥니다. 설정을 완료하려고 항상 성공하는 가상 핸들러를 만들지 마세요.

import { withTelemetry } from "@/lib/with-telemetry";

export const GET = withTelemetry(existingGET, "/api/reports/:id");

실제 호출 확인

앱에서 승인된 작업을 실행하고 Telemetry 테이블을 조회합니다. 라우트, 메서드, 시간, 결과, 상태를 방금 관측한 작업과 대조합니다. HTTP 수락만으로는 검증되지 않습니다. 오프라인 테스트, 데모 라우트, 에이전트 QA 실행은 고객 통합이 아닙니다. 가상 전송에는 telemetry_quickstart를 사용합니다.

SELECT invocation_id, route_template, method, handler_outcome,
       status_code, latency_ms, environment, timestamp_utc
FROM nextjs_route_observed
WHERE timestamp_utc >= now() - INTERVAL '15 minutes'
ORDER BY timestamp_utc DESC
LIMIT 20;

보장하지 않는 사항

Next.js after는 응답이 끝난 뒤 전송을 예약합니다. 영구 큐가 아니므로 실행 시간 제한, 종료, 시간 초과, 네트워크 장애로 이벤트가 유실될 수 있습니다. 전송 제한은 2초이며 경고는 비공개 데이터가 없는 고정 문구입니다. 자동 재시도나 중복 제거를 보장하지 않습니다. 기존 로그를 유지하고 필수 감사 기록에는 영구 전송 경로를 사용하세요.

latency_ms는 핸들러가 반환하거나 던질 때 끝나며 이벤트 전송 시간은 제외합니다. returned_response는 4xx나 5xx일 수도 있습니다. threw에는 프레임워크 리디렉션이나 제어 흐름도 포함될 수 있어 자동으로 서버 장애라고 판단할 수 없습니다. 키 누락과 원격 측정 실패가 원래 응답이나 예외를 바꾸면 안 됩니다. 배포 전에 자신의 실행 환경에서 확인하세요.

프레임워크 참고와 다음 단계

Next.js after 참고 문서는 버전과 배포 지원을 설명합니다. 정적 내보내기는 지원되지 않으며 어댑터는 명시적 지원이 필요합니다. 응답 유지, 예외 및 텔레메트리 전송 실패를 격리된 Next.js 16.3.8 개발용 App Router 앱에서 확인했습니다. 이벤트 전송은 가로채고 외부 네트워크는 비활성화했습니다. 실제 Telemetry 수집이나 사용자의 프로덕션 호스트를 검증한 것은 아닙니다. 이벤트 수집 검증과 JavaScript SDK 가이드로 계측을 확장하세요.

코딩 에이전트와 함께 이 문서를 사용하세요.