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

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

規約

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

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

たとえば、Next.jsをOpenTelemetryおよび@vercel/otelと連携させる場合

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

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

補足:

• `instrumentation`ファイルは、プロジェクトのルートに配置し、`app`または`pages`ディレクトリ内には配置しないでください。`src`フォルダを使用している場合は、`src`内に`pages`や`app`と同じ階層に配置してください。
• `pageExtensions`設定オプションを使用してサフィックスを追加する場合、`instrumentation`ファイル名もそれに合わせて更新する必要があります。

例

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

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

ファイルは、`register`関数内でJavaScriptの`import`構文を使用してインポートすることをお勧めします。以下の例は、`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')
  }
}