كيفية إعداد الأدوات (Instrumentation)

أدوات القياس (Instrumentation) هي عملية استخدام التعليمات البرمجية لدمج أدوات المراقبة والتسجيل في تطبيقك. هذا يسمح لك بتتبع أداء وسلوك التطبيق، وتصحيح المشكلات في بيئة الإنتاج.

الاتفاقية (Convention)

لإعداد أدوات القياس، قم بإنشاء ملف instrumentation.ts|js في الدليل الرئيسي لمشروعك (أو داخل مجلد src إذا كنت تستخدم واحدًا).

ثم قم بتصدير دالة register في الملف. سيتم استدعاء هذه الدالة مرة واحدة عند بدء تشغيل نسخة جديدة من خادم Next.js.

على سبيل المثال، لاستخدام Next.js مع OpenTelemetry و @vercel/otel:

import { registerOTel } from '@vercel/otel'

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

import { registerOTel } from '@vercel/otel'

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

راجع مثال Next.js مع OpenTelemetry للحصول على تنفيذ كامل.

معلومة مفيدة:

• يجب أن يكون ملف instrumentation في جذر مشروعك وليس داخل مجلد app أو pages. إذا كنت تستخدم مجلد src، فضع الملف داخل src بجانب pages و app.
• إذا كنت تستخدم خيار التكوين pageExtensions لإضافة لاحقة، فستحتاج أيضًا إلى تحديث اسم ملف instrumentation ليتطابق.

أمثلة

استيراد ملفات ذات تأثيرات جانبية

في بعض الأحيان، قد يكون من المفيد استيراد ملف في التعليمات البرمجية الخاصة بك بسبب التأثيرات الجانبية التي سيسببها. على سبيل المثال، قد تستورد ملفًا يحدد مجموعة من المتغيرات العامة، ولكن لا تستخدم الملف المستورد صراحةً في التعليمات البرمجية الخاصة بك. سيكون لديك مع ذلك إمكانية الوصول إلى المتغيرات العامة التي أعلن عنها الحزمة.

نوصي باستيراد الملفات باستخدام صيغة استيراد JavaScript import داخل دالة register الخاصة بك. يوضح المثال التالي استخدامًا أساسيًا لـ import في دالة register:

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

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

معلومة مفيدة:

نوصي باستيراد الملف من داخل دالة register، بدلاً من أعلى الملف. من خلال القيام بذلك، يمكنك تجميع جميع التأثيرات الجانبية في مكان واحد في التعليمات البرمجية الخاصة بك، وتجنب أي عواقب غير مقصودة من الاستيراد العام في أعلى الملف.

استيراد تعليمات برمجية خاصة ببيئة التشغيل

يستدعي 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')
  }
}

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

  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./instrumentation-edge')
  }
}