メインコンテンツまでスキップ

Instrumentation

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

規約​

Instrumentationを設定するには、プロジェクトのルートディレクトリにinstrumentation.ts|jsファイルを作成します（もしsrcフォルダを使用している場合はその中に作成してください）。

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

例えば、Next.jsをOpenTelemetryと@vercel/otelと一緒に使う場合：

instrumentation.ts
import { registerOTel } from '@vercel/otel'

// Next.jsアプリのOpenTelemetryを登録する
export function register() {
  registerOTel('next-app')
}

完全な実装については、Next.js with OpenTelemetry exampleをご覧ください。

Good to know:

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

例​

副作用を伴うファイルのインポート​

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

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

instrumentation.ts
// 副作用があるパッケージのインポート
export async function register() {
  await import('package-with-side-effect')
}

Good to know:

ファイルの先頭ではなく、register関数内からファイルをインポートすることをお勧めします。これにより、すべての副作用をコード内で1か所に集約でき、ファイルの先頭でグローバルにインポートすることによる予期せぬ影響を避けることができます。

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

Next.jsはすべての環境でregisterを呼び出すため、特定のランタイムをサポートしないコードを条件付きでインポートすることが重要です（例：EdgeまたはNode.js）。現在の環境を取得するためにNEXT_RUNTIME環境変数を使用できます：

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