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

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

規則

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

次に、ファイル内で`register`関数をエクスポートします。この関数は、新しいNext.jsサーバーインスタンスが開始されたときに**一度だけ**呼び出されます。

たとえば、Next.jsをOpenTelemetryおよび@vercel/otelと組み合わせて使用するには、次のようにします。

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

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

知っておくと良いこと:

• instrumentationファイルは、プロジェクトのルートに配置する必要があり、appまたはpagesディレクトリの中には配置しないでください。 srcフォルダを使用している場合は、pagesとappと並んでsrc内にファイルを配置します。
• 接尾辞を追加するためにpageExtensions設定オプションを使用する場合は、instrumentationファイル名も一致するように更新する必要があります。

例

副作用のあるファイルのインポート

場合によっては、発生する副作用のためにコードでファイルをインポートすると便利な場合があります。たとえば、一連のグローバル変数を定義するファイルをインポートしても、コードでインポートされたファイルを明示的に使用することはありません。それでも、パッケージが宣言したグローバル変数にアクセスできます。

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

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