Menu

インストゥルメンテーションの設定方法

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

規約

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

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

例えば、Next.jsをOpenTelemetryと@vercel/otelと共に使用するには：

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

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

補足:

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

例

副作用を持つファイルのインポート

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

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

instrumentation.ts
TypeScript
export async function register() {
  await import('package-with-side-effect')
}

補足:

ファイルの先頭ではなく、register関数内からファイルをインポートすることをお勧めします。これにより、コード内の副作用をひとつの場所に集中させ、ファイルの先頭でグローバルにインポートすることによる意図しない結果を避けることができます。

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

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

instrumentation.ts
TypeScript
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation-node')
  }
 
  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./instrumentation-edge')
  }
}

インストゥルメンテーションについてさらに学ぶ

instrumentation.js

instrumentation.js ファイルのAPI リファレンス。