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

Instrumentation

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

規約​

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

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

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

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

// 次のように含めます
export function register() {
  registerOTel('next-app')
}

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

Good to know:

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

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