コンテンツにスキップ
Pages RouterGuidesInstrumentation

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

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

規約

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

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

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

instrumentation.ts
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
export async function register() {
  await import('package-with-side-effect')
}

知っておくと良いこと

ファイルのトップレベルでのグローバルインポートによる意図しない結果を避けるため、ファイルのトップレベルでインポートするのではなく、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')
  }
}