계측

계측은 코드를 사용하여 모니터링 및 로깅 도구를 애플리케이션에 통합하는 과정입니다. 이를 통해 애플리케이션의 성능과 동작을 추적하고 프로덕션 환경에서 문제를 디버그할 수 있습니다.

규칙

계측을 설정하려면 프로젝트의 루트 디렉토리에 instrumentation.ts|js 파일을 생성하세요 (src 폴더를 사용하는 경우 해당 폴더 내부에 생성).

그런 다음 파일에서 register 함수를 내보내세요. 이 함수는 새로운 Next.js 서버 인스턴스가 시작될 때 한 번 호출됩니다.

예를 들어, Next.js를 OpenTelemetry와 @vercel/otel과 함께 사용하려면:

import { registerOTel } from "@vercel/otel";
 
export function register() {
  registerOTel("next-app");
}

import { registerOTel } from "@vercel/otel";
 
export function register() {
  registerOTel("next-app");
}

전체 구현은 OpenTelemetry를 사용한 Next.js 예제를 참조하세요.

알아두면 좋은 점

• 이 기능은 실험적입니다. 사용하려면 next.config.js에서 experimental.instrumentationHook = true;를 명시적으로 정의해야 합니다.
• instrumentation 파일은 프로젝트의 루트에 있어야 하며 app 또는 pages 디렉토리 안에 있으면 안 됩니다. src 폴더를 사용하는 경우 pages와 app 옆의 src 안에 파일을 배치하세요.
• pageExtensions 구성 옵션을 사용하여 접미사를 추가하는 경우, instrumentation 파일 이름도 이에 맞게 업데이트해야 합니다.

예시

부작용이 있는 파일 가져오기

때로는 코드에서 부작용 때문에 파일을 가져오는 것이 유용할 수 있습니다. 예를 들어, 일련의 전역 변수를 정의하는 파일을 가져올 수 있지만 코드에서 가져온 파일을 명시적으로 사용하지 않을 수 있습니다. 그래도 패키지가 선언한 전역 변수에 접근할 수 있습니다.

register 함수 내에서 JavaScript import 구문을 사용하여 파일을 가져오는 것을 권장합니다. 다음 예제는 register 함수에서 import의 기본 사용법을 보여줍니다:

export async function register() {
  await import("package-with-side-effect");
}

export async function register() {
  await import("package-with-side-effect");
}

알아두면 좋은 점:

파일 상단에서 전역적으로 가져오는 대신 register 함수 내에서 파일을 가져오는 것을 권장합니다. 이렇게 하면 코드의 한 곳에 모든 부작용을 함께 배치할 수 있으며, 파일 상단에서 전역적으로 가져올 때 발생할 수 있는 의도하지 않은 결과를 피할 수 있습니다.

런타임별 코드 가져오기

Next.js는 모든 환경에서 register를 호출하므로, 특정 런타임을 지원하지 않는 코드(예: Edge 또는 Node.js)를 조건부로 가져오는 것이 중요합니다. NEXT_RUNTIME 환경 변수를 사용하여 현재 환경을 확인할 수 있습니다:

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./instrumentation-node");
  }
 
  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./instrumentation-edge");
  }
}

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./instrumentation-node");
  }
 
  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./instrumentation-edge");
  }
}