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

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

規約

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

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

例えば、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の例を参照してください。

補足：

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