instrumentation.js

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

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

エクスポート

`register` (オプション)

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

import { registerOTel } from '@vercel/otel'

export function register() {
  registerOTel('next-app')
}

`onRequestError` (オプション)

オプションで onRequestError 関数をエクスポートして、サーバーエラーを任意のカスタムオブザーバビリティプロバイダーに追跡できます。

onRequestError 内で非同期タスクを実行する場合、それらが待機されることを確認してください。onRequestError は Next.js サーバーがエラーを捕捉したときにトリガーされます。
error インスタンスは、元のエラーインスタンスではない可能性があります。Server Components のレンダリング中に発生した場合、React によって処理されるためです。これが発生した場合、エラーの digest プロパティを使用して実際のエラータイプを識別できます。

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 // 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`	`onRequestError` の導入、`instrumentation` が安定版に
`v14.0.4`	`instrumentation` の Turbopack サポート
`v13.2.0`	`instrumentation` が実験的機能として導入

計装 (Instrumentation)

Next.jsアプリでサーバー起動時にコードを実行する計装 (Instrumentation) の使用方法を学びましょう