التجهيز (Instrumentation)

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

الاصطلاح

لإعداد التجهيز الآلي، قم بإنشاء ملف 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 للحصول على تنفيذ كامل.

معلومة مفيدة

• هذه الميزة تجريبية. لاستخدامها، يجب عليك الموافقة صراحةً عن طريق تعريف experimental.instrumentationHook = true; في ملف next.config.js.
• يجب أن يكون ملف instrumentation في جذر مشروعك وليس داخل مجلد app أو pages. إذا كنت تستخدم مجلد src، فضع الملف داخل src بجانب pages و app.
• إذا كنت تستخدم خيار pageExtensions لإضافة لاحقة، فستحتاج أيضًا إلى تحديث اسم ملف instrumentation ليتطابق.

أمثلة

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

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

نوصي باستيراد الملفات باستخدام صيغة import في JavaScript داخل دالة 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')
  }
}