Menu

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

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

規約

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

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

たとえば、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関数内からインポートすることをお勧めします。これにより、コード内の1か所にすべての副作用を配置でき、ファイル最上部でグローバルにインポートするときの意図しない結果を回避できます。

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

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リファレンス