Instrumentation

Instrumentation は、あなたのアプリケーションに監視およびログ記録ツールを統合するために code を使用するプロセスです。これにより、アプリケーションのパフォーマンスと振る舞いを追跡し、production での問題を debugging することが可能になります。

Convention

instrumentation を設定するには、プロジェクトのroot ディレクトリーにinstrumentation.ts|js ファイルを作成します(src フォルダを使用している場合はその内部)。

その後、ファイルでregisterという機能を export します。この機能は新しい Next.js server インスタンスが開始されたときに一度だけ呼び出されます。

例えば、OpenTelemetry と @vercel/otel を Next.js で使用するには：

import { registerOTel } from '@vercel/otel'

export function register() {
  registerOTel('next-app')
}

import { registerOTel } from '@vercel/otel'

export function register() {
  registerOTel('next-app')
}

Next.js with OpenTelemetry example を参照して、完全な実装をご覧ください。

Good to know

• この機能は実験的です。これを使用するには、あなたのnext.config.jsでexperimental.instrumentationHook = true; と明示的に定義してオプトインする必要があります。
• instrumentationファイルはプロジェクトの root にあるべきで、appやpagesディレクトリ内にはありません。srcフォルダを使用している場合は、srcの中にpagesとappと並べてファイルを配置してください。
• pageExtensions config option を使用してサフィックスを追加する場合、instrumentationのファイル名も合わせて更新する必要があります。

Examples

副作用を伴うファイルのインポート

時には、副作用が発生するためにファイルを import して、それがあなたの code に利用されることもあるかもしれません。例えば、グローバル variables のセットを定義するファイルを import するかもしれませんが、その import したファイルをあなたの code で明示的には never 使用しないかもしれません。それでも、パッケージが宣言したグローバル variables にはアクセスできるでしょう。

register 関数内で import syntax を使用してファイルをインポートすることをお勧めします。次の例は、register関数内でのimportの基本的な使用方法を示しています：

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

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

Good to know:

ファイルのインポートは、ファイルのトップではなく、register関数内から行うことをお勧めします。これにより、すべての副作用を code の一か所に配置し、ファイルのトップでグローバルにインポートすることによる意図しない結果を避けることができます。

Runtime 固有の code のインポート

Next.js はすべての環境でregisterを呼び出します、したがって、特定の runtimes(例：Edge や Node.js) をサポートしていない任意の code を条件付きで import することが重要です。現在の環境を取得するために、NEXT_RUNTIME環境 variable を使用することができます:

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')
  }
}