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

インストルメンテーションとは、コードを使用してアプリケーションにモニタリングツールやロギングツールを統合するプロセスです。これにより、アプリケーションのパフォーマンスや動作を追跡し、本番環境での問題をデバッグできるようになります。

規約

インストルメンテーションを設定するには、プロジェクトのルートディレクトリ（またはsrcフォルダを使用している場合はその中）にinstrumentation.ts|jsファイルを作成します。

次に、そのファイルでregister関数をエクスポートします。この関数は、新しいNext.jsサーバーインスタンスが起動する際に1回呼び出されます。

例えば、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')
}

完全な実装についてはNext.js with OpenTelemetryの例を参照してください。

知っておくと便利

• この機能は実験的です。使用するには、next.config.jsでexperimental.instrumentationHook = true;を明示的に設定する必要があります。
• instrumentationファイルはプロジェクトのルートに配置し、appやpagesディレクトリ内には配置しないでください。srcフォルダを使用している場合は、pagesやappと同階層に配置します。
• 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関数内からインポートすることを推奨します。これにより、すべての副作用をコード内の1か所にまとめることができ、ファイルのトップレベルでグローバルにインポートすることによる意図しない影響を避けられます。

ランタイム固有のコードのインポート

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