インストルメンテーション

プロジェクトのルートディレクトリ（またはsrcフォルダを使用している場合はその中）にinstrumentation.ts（または.js）ファイルを作成し、registerという名前の関数をエクスポートすると、新しいNext.jsサーバーインスタンスが起動するたびにその関数が呼び出されます。

知っておくとよいこと

この機能は実験的です。使用するには、next.config.jsでexperimental.instrumentationHook = true;を明示的に定義する必要があります。

instrumentationファイルはプロジェクトのルートに配置し、appやpagesディレクトリ内には置かないでください。srcフォルダを使用している場合は、pagesやappと同階層にファイルを配置します。

pageExtensions設定オプションを使用してサフィックスを追加する場合、instrumentationファイル名もそれに合わせて更新する必要があります。

基本的なwith-opentelemetryの例を用意していますので、参考にしてください。

register関数がデプロイされると、コールドブートのたびに（ただし各環境で正確に1回）呼び出されます。

コード内で副作用を引き起こすためにファイルをインポートすると便利な場合があります。例えば、グローバル変数のセットを定義するファイルをインポートしても、コード内で明示的にそのファイルを使用しない場合でも、パッケージが宣言したグローバル変数にアクセスできます。

instrumentation.tsで副作用のあるファイルをインポートできます。以下の例に示すように、register関数内で使用したい場合があります:

import { init } from 'package-init'

export function register() {
  init()
}

import { init } from 'package-init'

export function register() {
  init()
}

ただし、副作用のあるファイルはregister関数内でimportを使用してインポートすることを推奨します。以下の例はregister関数内での基本的なimportの使用方法を示しています:

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

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

この方法により、すべての副作用をコード内の1か所にまとめて配置でき、ファイルのインポートによる意図しない結果を回避できます。

registerはすべての環境で呼び出されるため、edgeとnodejsの両方をサポートしていないコードは条件付きでインポートする必要があります。現在の環境を取得するには環境変数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')
  }
}