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

instrumentation.js

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

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

エクスポート

register(オプション)

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

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

// register関数をエクスポートします
export function register() {
registerOTel('next-app')
}

onRequestError(オプション)

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

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

// onRequestError関数をエクスポートします
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',
},
})
}

パラメータ

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

Types
// onRequestError関数の型定義
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' // 'dynamic-resume'はPPR用
}
): 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 runtimeの両方で動作しますが、process.env.NEXT_RUNTIMEを使用して特定のランタイムをターゲットにすることができます。

instrumentation.js
// register関数をエクスポートします
export function register() {
if (process.env.NEXT_RUNTIME === 'edge') {
return require('./register.edge')
} else {
return require('./register.node')
}
}

// onRequestError関数をエクスポートします
export function onRequestError() {
if (process.env.NEXT_RUNTIME === 'edge') {
return require('./on-request-error.edge')
} else {
return require('./on-request-error.node')
}
}

バージョン履歴

バージョン変更内容
v15.0.0onRequestErrorが導入され、instrumentationが安定版に
v14.0.4instrumentationに対するTurbopackのサポート
v13.2.0instrumentationが実験的機能として導入されました