مقدمه
Instrumentation فرآیند ثبت رفتار و عملکرد اپلیکیشن با استفاده از کد است. این قابلیت به شما کمک میکند تا مشکلات را در محیط production ردیابی کرده و عملکرد سیستم را مانیتور کنید.
ساختار پیشنهادی
برای راهاندازی instrumentation در Next.js، فایل instrumentation.ts یا instrumentation.js را در ریشه پروژه یا داخل پوشه src ایجاد کنید.
در این فایل، تابع register را export کنید. این تابع هنگام راهاندازی سرور Next.js یکبار اجرا میشود.
مثال: اتصال به OpenTelemetry
import { registerOTel } from '@vercel/otel'
export function register() {
registerOTel('next-app')
}این کد OpenTelemetry را برای اپلیکیشن با نام next-app فعال میکند.
نکات مهم
- فایل instrumentation باید در ریشه پروژه باشد، نه داخل پوشه
appیاpages - اگر از
srcاستفاده میکنید، فایل را کنار پوشههایpagesوappقرار دهید - اگر از گزینه
pageExtensionsاستفاده کردهاید، نام فایل instrumentation را مطابق آن تنظیم کنید
وارد کردن فایلهای دارای اثر جانبی
گاهی لازم است فایلی را فقط بهخاطر اثر جانبی آن وارد کنید، مثلاً برای تعریف متغیرهای سراسری. توصیه میشود این کار را داخل تابع register انجام دهید:
export async function register() {
await import('package-with-side-effect')
}این روش باعث میشود تمام اثرات جانبی در یک نقطه متمرکز شوند و از وارد کردن ناخواسته در سطح بالا جلوگیری شود.
وارد کردن کد وابسته به runtime
تابع register در تمام محیطها اجرا میشود. بنابراین باید کدهایی که فقط در محیط خاصی اجرا میشوند را بهصورت شرطی وارد کنید:
export async function register() {
if (process.env.NEXT_RUNTIME === 'nodejs') {
await import('./instrumentation-node')
}
if (process.env.NEXT_RUNTIME === 'edge') {
await import('./instrumentation-edge')
}
}این روش از بروز خطا در محیطهایی مانند Edge جلوگیری میکند.
جمعبندی
با راهاندازی instrumentation در Next.js میتوانید ابزارهای مانیتورینگ را بهصورت امن و ساختاریافته به اپلیکیشن خود متصل کنید. استفاده از فایل instrumentation.ts، مدیریت کدهای جانبی و تفکیک محیطهای اجرایی از اصول کلیدی در این فرآیند هستند.