ابزارنگاری

ابزارنگاری فرآیندی است که در آن از کد برای ادغام ابزارهای مانیتورینگ و لاگ‌گیری در برنامه‌ی شما استفاده می‌شود. این کار به شما امکان می‌دهد عملکرد و رفتار برنامه‌ی خود را ردیابی کنید و مشکلات را در محیط تولید production اشکال‌زدایی نمایید.

قرارداد

برای راه‌اندازی ابزارنگاری، فایل instrumentation.ts|js را در پوشه‌ی ریشه‌ی پروژه‌ی خود (یا داخل پوشه‌ی src اگر از آن استفاده می‌کنید) ایجاد کنید.

سپس، یک تابع register را در این فایل خروجی بگیرید. این تابع تنها یک بار، هنگام راه‌اندازی یک نمونه‌ی instance سرور جدید Next.js، فراخوانی می‌شود.

به عنوان مثال، برای استفاده از Next.js با OpenTelemetry (opens in a new tab) و @vercel/otel (opens in a new tab):

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

برای مشاهده‌ی پیاده‌سازی کامل، به مثال Next.js با OpenTelemetry (opens in a new tab) مراجعه کنید.

خوب است بدانید

• این ویژگی آزمایشی است. برای استفاده از آن، باید با تعریف experimental.instrumentationHook = true; در فایل next.config.js خود به صراحت اعلام کنید که می‌خواهید از آن استفاده کنید.
• فایل instrumentation باید در ریشه‌ی پروژه‌‌ی شما قرار گیرد و نباید داخل پوشه‌های app یا pages باشد. اگر از پوشه‌ی src استفاده می‌کنید، این فایل را در کنار پوشه‌های pages و app داخل src قرار دهید.
• اگر از گزینه پیکربندی pageExtensions برای اضافه کردن پسوند به صفحات استفاده می‌کنید، باید نام فایل instrumentation را نیز برای مطابقت با پسوند جدید به‌روزرسانی کنید.

مثال ها

ایمپورت کردن فایل‌ها با اثرات جانبی side effects

گاهی اوقات، ممکن است مفید باشد که یک فایل را در کد خود ایمپورت کنید زیرا باعث ایجاد عوارض جانبی می‌شود. برای مثال، ممکن است فایلی را ایمپورت کنید که مجموعه‌ای از متغیرهای سراسری را تعریف می‌کند، اما هرگز از فایل ایمپورت شده در کد خود به طور صریح استفاده نکنید. همچنان به متغیرهای سراسری‌ای که بسته اعلام کرده است، دسترسی خواهید داشت.

ما توصیه می‌کنیم فایل‌ها را با استفاده از سینتکس import جاوااسکریپت درون تابع register خود ایمپورت کنید. مثال زیر استفاده‌ی پایه‌ای از import در یک تابع register را نشان می‌دهد:

export async function register() {
	await import('package-with-side-effect')
}

خوب است بدانید:

توصیه می‌کنیم فایل را درون تابع register ایمپورت کنید، نه در ابتدای فایل. با این کار می‌توانید تمام عوارض جانبی side effects را در یک مکان در کد خود قرار دهید و از هرگونه پیامد ناخواسته‌ی ناشی از ایمپورت کردن سراسری در ابتدای فایل جلوگیری کنید.

ایمپورت کردن کدی که وابسته به runtime برنامه است

Next.js تابع register را در تمام محیط‌ها فراخوانی می‌کند، بنابراین مهم است که هر کدی که از زمان‌های اجرای خاصی (مانند Edge یا Node.js) پشتیبانی نمی‌کند را به صورت شرطی وارد کنید. می‌توانید از متغیر محیطی NEXT_RUNTIME برای دریافت محیط فعلی استفاده کنید:

export async function register() {
	if (process.env.NEXT_RUNTIME === 'nodejs') {
		await import('./instrumentation-node')
	}
 
	if (process.env.NEXT_RUNTIME === 'edge') {
		await import('./instrumentation-edge')
	}
}