コンテンツにスキップ

instrumentation.js

instrumentation.js|ts ファイルは、アプリケーションに監視ツールを統合するために使用され、パフォーマンスと動作を追跡し、本番環境での問題をデバッグすることができます。

これを使用するには、アプリケーションのルート、または使用している場合は src フォルダー内にファイルを配置します。

エクスポート

register (オプション)

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

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

onRequestError (オプション)

この API は、Next.js canary で利用できます。

オプションで、onRequestError 関数をエクスポートして、カスタム監視プロバイダーにサーバーエラーを追跡できます。

  • onRequestError で非同期タスクを実行している場合は、それらが待機されていることを確認してください。onRequestError は、Next.js サーバーがエラーをキャプチャしたときにトリガーされます。
  • error インスタンスは、サーバーコンポーネントのレンダリング中に発生した場合に 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',
    },
  })
}

パラメータ

この関数は、errorrequest、および context の 3 つのパラメーターを受け入れます。

export function onRequestError(
  error: { digest: string } & Error,
  request: {
    path: string // resource path, e.g. /blog?name=foo
    method: string // request method. e.g. GET, POST, etc
    headers: { [key: string]: string }
  },
  context: {
    routerKind: 'Pages Router' | 'App Router' // the router type
    routePath: string // the route file path, e.g. /app/blog/[dynamic]
    routeType: 'render' | 'route' | 'action' | 'middleware' // the context in which the error occurred
    renderSource:
      | 'react-server-components'
      | 'react-server-components-payload'
      | 'server-rendering'
    revalidateReason: 'on-demand' | 'stale' | undefined // undefined is a normal request without revalidation
    renderType: 'dynamic' | 'dynamic-resume' // 'dynamic-resume' for PPR
  }
): void | Promise<void>
  • error: キャッチされたエラー自体 (型は常に Error) と、エラーの一意の ID である digest プロパティ。
  • request: エラーに関連付けられた読み取り専用のリクエスト情報。
  • context: エラーが発生したコンテキスト。これは、ルーターのタイプ (App Router または Pages Router) および/または (サーバーコンポーネント ('render')、ルートハンドラー ('route')、サーバーアクション ('action')、またはミドルウェア ('middleware')) にすることができます。

ランタイムの指定

instrumentation.js ファイルは Node.js と Edge ランタイムの両方で動作しますが、特定のランタイムを対象とするために process.env.NEXT_RUNTIME を使用できます。

instrumentation.js
export function register() {
  if (process.env.NEXT_RUNTIME === 'edge') {
    return require('./register.edge')
  } else {
    return require('./register.node')
  }
}
 
export function onRequestError() {
  if (process.env.NEXT_RUNTIME === 'edge') {
    return require('./on-request-error.edge')
  } else {
    return require('./on-request-error.node')
  }
}

バージョン履歴

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