Menu

instrumentation.js

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

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

エクスポート

register（オプション）

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

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

onRequestError（オプション）

任意のカスタム観測プロバイダーにサーバーエラーを追跡するために、onRequestError関数をエクスポートできます。

  • onRequestErrorで非同期タスクを実行する場合は、それらを必ず待機してください。onRequestErrorは、Next.jsサーバーがエラーをキャプチャしたときにトリガーされます。
  • エラーインスタンスは、Server Componentsのレンダリング中に発生した場合、元のエラーインスタンスではない可能性があります。そのような場合、エラーの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',
    },
  })
}
instrumentation.js
export async function onRequestError(err, request, context) {
  await fetch('https://.../report-error', {
    method: 'POST',
    body: JSON.stringify({
      message: err.message,
      request,
      context,
    }),
    headers: {
      'Content-Type': 'application/json',
    },
  })
}

パラメータ

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

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 // 再検証なしの通常のリクエストの場合は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') {
    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を実験的機能として導入

インストゥルメンテーションについてさらに詳しく学ぶ

インストルメンテーション

Next.jsアプリのサーバー起動時にコードを実行するためのインストルメンテーションの使用方法を学ぶ