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

instrumentation.js

instrumentation.js|tsファイルは、アプリケーションに観測ツールを統合するために使用されます。これにより、アプリケーションのパフォーマンスや動作を追跡し、プロダクションでの問題をデバッグできます。

使用するには、ファイルをアプリケーションのrootに配置するか、srcフォルダの中に配置します（使用している場合）。

エクスポート​

register (オプショナル)​

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

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

// OTelを登録する関数
export function register() {
  registerOTel('next-app') // next-appという名前で登録
}

onRequestError (オプショナル)​

onRequestError関数をエクスポートして、サーバーエラーをカスタムの観測プロバイダーに追跡することができます。

  • onRequestErrorで非同期タスクを実行する場合、必ずawaitしてください。onRequestErrorは、Next.jsサーバーがエラーをキャプチャしたときにトリガーされます。
  • errorインスタンスは、元のエラーインスタンスではない可能性があります。これは、Server Componentsのレンダリング中に発生した場合、Reactによって処理される可能性があるためです。このような場合、digestプロパティを使用して実際のエラータイプを識別できます。
instrumentation.ts
import { type Instrumentation } from 'next'

// エラーをリクエストする関数
export const onRequestError: Instrumentation.onRequestError = async (
  err,
  request,
  context
) => {
  // エラーレポートを送信
  await fetch('https://.../report-error', {
    method: 'POST',
    body: JSON.stringify({
      message: err.message,
      request,
      context,
    }),
    headers: {
      'Content-Type': 'application/json',
    },
  })
}

パラメーター​

この関数は、3つのパラメーター、error、request、およびcontextを受け取ります。

Types
// エラーをリクエストする関数
export function onRequestError(
  error: { digest: string } & Error,
  request: {
    path: string // リソースのパス、例: /blog?name=foo
    method: string // リクエストメソッド、例: GET, POSTなど
    headers: { [key: string]: string } // ヘッダー情報
  },
  context: {
    routerKind: 'Pages Router' | 'App Router' // ルーターの種類
    routePath: string // ルートファイルのパス、例: /app/blog/[dynamic]
    routeType: 'render' | 'route' | 'action' | 'middleware' // エラーが発生する文脈
    renderSource:
      | 'react-server-components'
      | 'react-server-components-payload'
      | 'server-rendering'
    revalidateReason: 'on-demand' | 'stale' | undefined // revalidationなしの通常リクエストはundefined
    renderType: 'dynamic' | 'dynamic-resume' // PPRには'dynamic-resume'
  }
): void | Promise<void>
  • error: キャッチされたエラー自体（型は常にError）と、エラーの一意のIDであるdigestプロパティです。
  • request: エラーに関連付けられたリクエスト情報（読み取り専用）です。
  • context: エラーが発生した文脈です。これには、ルーターの種類（AppまたはPages Router）、そして（Server Components（'render'）、Route Handlers（'route'）、Server Actions（'action'）、またはMiddleware（'middleware'））が含まれます。

ランタイムの指定​

instrumentation.jsファイルは、Node.jsとEdgeランタイムの両方で動作します。ただし、process.env.NEXT_RUNTIMEを使用して特定のランタイムをターゲットにすることができます。

instrumentation.js
// ランタイムに基づいてモジュールをロードする関数
export function register() {
  if (process.env.NEXT_RUNTIME === 'edge') {
    // Edgeランタイム用の登録モジュールをロード
    return require('./register.edge')
  } else {
    // Node.jsランタイム用の登録モジュールをロード
    return require('./register.node')
  }
}

// エラーリクエスト関数のロード
export function onRequestError() {
  if (process.env.NEXT_RUNTIME === 'edge') {
    // Edgeランタイム用のエラーハンドラーをロード
    return require('./on-request-error.edge')
  } else {
    // Node.jsランタイム用のエラーハンドラーをロード
    return require('./on-request-error.node')
  }
}

バージョン履歴​

バージョン変更点
v15.0.0-RConRequestErrorが導入され、instrumentationが安定版になりました
v14.0.4instrumentationのTurbopackサポート
v13.2.0instrumentationが実験的な機能として導入されました