Instrumentation

Instrumentation은 모니터링 및 로깅 도구를 애플리케이션에 통합하기 위해 코드를 사용하는 프로세스입니다. 이를 통해 애플리케이션의 성능 및 동작을 추적하고, 프로덕션에서 발생하는 문제를 디버깅할 수 있습니다.

Convention

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

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

예를 들어, Next.js를 OpenTelemetry (opens in a new tab) 및 @vercel/otel (opens in a new tab)과 함께 사용하려면 다음과 같이 합니다:

instrumentation.ts

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

instrumentation.js

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

완전한 구현을 위해 Next.js with OpenTelemetry example (opens in a new tab)을 참조하세요.

알아두면 좋은 점

이 기능은 실험적입니다. 사용하려면 next.config.js에서 experimental.instrumentationHook = true;로 명시적으로 설정해야 합니다.

instrumentation 파일은 프로젝트의 루트에 있어야 하며, app 또는 pages 디렉토리 내부에 있어서는 안 됩니다. src 폴더를 사용하는 경우 src 내의 pages 및 app과 함께 파일을 배치하세요.

pageExtensions 구성 옵션을 사용하여 접미사를 추가한 경우, instrumentation 파일 이름도 일치하도록 업데이트해야 합니다.

Examples

Importing files with side effects

때때로 부수 효과를 일으키는 파일을 코드에 가져오는 것이 유용할 수 있습니다. 예를 들어, 전역 변수를 정의하는 파일을 가져오지만 코드에서 명시적으로 해당 파일을 사용하지 않는 경우가 있을 수 있습니다. 여전히 패키지가 선언한 전역 변수에 접근할 수 있습니다.

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

instrumentation.ts

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

instrumentation.js

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

알아두면 좋은 점:

파일 상단이 아닌 register 함수 내에서 파일을 가져오는 것을 권장합니다. 이렇게 하면 코드의 모든 부수 효과를 한 곳에 모아 둘 수 있으며, 파일 상단에서 전역으로 가져오는 것에 따른 의도하지 않은 결과를 피할 수 있습니다.

Importing runtime-specific code

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

instrumentation.ts

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

instrumentation.js

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

Lazy Loading Open Telemetry