Instrumentation

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

Good to know:

この機能は実験的なものです。この機能を使用するには、next.config.jsでexperimental.instrumentationHook = true;と定義して、明示的にオプトインする必要があります

instrumentationファイルは、appやpagesディレクトリではなく、プロジェクトのルートに置く必要があります。srcフォルダを使用している場合は、srcの中にpagesとappと一緒にファイルを置きます

pageExtensions設定オプションを使用して接尾子を追加する場合は、instrumentationのファイル名もそれに合わせて更新する必要があります

基本的な使用例としてwith-opentelemetryが用意されています

register関数がデプロイされると、コールドスタートするたびに呼び出されます（ただし、各環境で一度だけ）。

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

instrumentation.tsでは、register関数内で使用するために副作用のあるファイルをインポートできます：

your-project/instrumentation.ts
import { init } from 'package-init'

export function register() {
  init()
}

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

your-project/instrumentation.ts
export async function register() {
  await import('package-with-side-effect')
}

こうすることで、すべての副作用をコード内の一箇所に集めることができ、ファイルのインポートによる意図しない結果を避けることができます。

すべての環境でregisterが呼び出されるので、edgeとnodejsの両方をサポートしていないコードは条件付きでインポートする必要があります。環境変数NEXT_RUNTIMEを使って現在の環境を取得できます。環境固有のコードをインポートする場合は次のようになります：

your-project/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')
  }
}