OpenTelemetry

معلومة مفيدة: هذه الميزة تجريبية، تحتاج إلى تفعيلها يدويًا عن طريق إضافة experimental.instrumentationHook = true; في ملف next.config.js.

المراقبة (Observability) ضرورية لفهم وتحسين سلوك وأداء تطبيق Next.js الخاص بك.

مع زيادة تعقيد التطبيقات، يصبح تحديد وتشخيص المشكلات أكثر صعوبة. من خلال استخدام أدوات المراقبة مثل التسجيل والمقاييس، يمكن للمطورين الحصول على رؤى حول سلوك التطبيق وتحديد مجالات التحسين. تمكن المراقبة المطورين من معالجة المشكلات بشكل استباقي قبل أن تصبح كبيرة وتوفير تجربة مستخدم أفضل. لذلك، يوصى بشدة باستخدام المراقبة في تطبيقات Next.js لتحسين الأداء وترشيد الموارد وتعزيز تجربة المستخدم.

نوصي باستخدام OpenTelemetry لإعداد تطبيقاتك. إنها طريقة محايدة للمنصة لإعداد التطبيقات تتيح لك تغيير مزود المراقبة دون تغيير الكود. اقرأ وثائق OpenTelemetry الرسمية لمزيد من المعلومات حول OpenTelemetry وكيفية عمله.

يستخدم هذا التوثيق مصطلحات مثل Span، Trace أو Exporter والتي يمكن العثور عليها جميعًا في دليل المراقبة الأساسي لـ OpenTelemetry.

يدعم Next.js إعداد OpenTelemetry مباشرة، مما يعني أننا قمنا بالفعل بإعداد Next.js نفسه. عند تفعيل OpenTelemetry، سنقوم تلقائيًا بتغليف جميع الأكواد مثل getStaticProps داخل spans مع سمات مفيدة.

معلومة مفيدة: نحن ندعم حاليًا روابط OpenTelemetry فقط في دوال serverless. لا نقدم أيًا منها لأكواد edge أو جانب العميل.

البدء

OpenTelemetry قابل للتوسيع ولكن إعداده بشكل صحيح قد يكون مطولًا. لهذا السبب أعددنا حزمة @vercel/otel لمساعدتك في البدء بسرعة. إنها غير قابلة للتوسيع ويجب عليك تكوين OpenTelemetry يدويًا إذا كنت بحاجة إلى تخصيص إعدادك.

استخدام `@vercel/otel`

للبدء، يجب تثبيت @vercel/otel:

Terminal

npm install @vercel/otel

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

import { registerOTel } from '@vercel/otel'

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

import { registerOTel } from '@vercel/otel'

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

معلومة مفيدة

يجب أن يكون ملف instrumentation في جذر مشروعك وليس داخل مجلد app أو pages. إذا كنت تستخدم مجلد src، فضع الملف داخل src بجانب pages و app.

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

لقد أنشأنا مثالًا أساسيًا with-opentelemetry يمكنك استخدامه.

تكوين OpenTelemetry يدويًا

إذا لم يكن الغلاف @vercel/otel مناسبًا لاحتياجاتك، يمكنك تكوين OpenTelemetry يدويًا.

أولاً، تحتاج إلى تثبيت حزم OpenTelemetry:

Terminal

npm install @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http

الآن يمكنك تهيئة NodeSDK في ملف instrumentation.ts. واجهات برمجة تطبيقات OpenTelemetry غير متوافقة مع وقت تشغيل edge، لذا تحتاج إلى التأكد من أنك تقوم باستيرادها فقط عندما يكون process.env.NEXT_RUNTIME === 'nodejs'. نوصي بإنشاء ملف جديد instrumentation.node.ts تقوم باستيراده شرطيًا فقط عند استخدام node:

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

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

import { NodeSDK } from '@opentelemetry/sdk-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { Resource } from '@opentelemetry/resources'
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions'
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node'

const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'next-app',
  }),
  spanProcessor: new SimpleSpanProcessor(new OTLPTraceExporter()),
})
sdk.start()

import { NodeSDK } from '@opentelemetry/sdk-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { Resource } from '@opentelemetry/resources'
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions'
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node'

const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'next-app',
  }),
  spanProcessor: new SimpleSpanProcessor(new OTLPTraceExporter()),
})
sdk.start()

هذا يعادل استخدام @vercel/otel، لكنه قابل للتعديل والتوسيع. على سبيل المثال، يمكنك استخدام @opentelemetry/exporter-trace-otlp-grpc بدلاً من @opentelemetry/exporter-trace-otlp-http أو يمكنك تحديد سمات موارد إضافية.

اختبار إعدادك

تحتاج إلى جامع OpenTelemetry مع خلفية متوافقة لاختبار تتبع OpenTelemetry محليًا. نوصي باستخدام بيئة التطوير OpenTelemetry.

إذا كان كل شيء يعمل بشكل صحيح، يجب أن تكون قادرًا على رؤية نطاق الخادم الجذر المسمى كـ GET /requested/pathname. جميع النطاقات الأخرى من ذلك التتبع المحدد ستكون متداخلة تحته.

يتتبع Next.js نطاقات أكثر من تلك المنبعثة افتراضيًا. لرؤية المزيد من النطاقات، يجب عليك تعيين NEXT_OTEL_VERBOSE=1.

النشر

استخدام جامع OpenTelemetry

عند النشر مع جامع OpenTelemetry، يمكنك استخدام @vercel/otel. سيعمل هذا سواء على Vercel أو عند الاستضافة الذاتية.

النشر على Vercel

لقد تأكدنا من أن OpenTelemetry يعمل مباشرة على Vercel.

اتبع توثيق Vercel لربط مشروعك بمزود المراقبة.

الاستضافة الذاتية

النشر على منصات أخرى أيضًا مباشر. ستحتاج إلى تشغيل جامع OpenTelemetry الخاص بك لاستقبال ومعالجة بيانات المراقبة من تطبيق Next.js.

للقيام بذلك، اتبع دليل البدء لجامع OpenTelemetry، والذي سيرشدك خلال إعداد الجامع وتكوينه لاستقبال البيانات من تطبيق Next.js.

بمجرد تشغيل الجامع، يمكنك نشر تطبيق Next.js على المنصة التي تختارها باتباع أدلة النشر الخاصة بها.

المصدرون المخصصون

نوصي باستخدام جامع OpenTelemetry. إذا لم يكن ذلك ممكنًا على منصتك، يمكنك استخدام مصدر OpenTelemetry مخصص مع تكوين OpenTelemetry يدويًا

النطاقات المخصصة

يمكنك إضافة نطاق مخصص باستخدام واجهات برمجة تطبيقات OpenTelemetry.

Terminal

npm install @opentelemetry/api

يوضح المثال التالي دالة تقوم جلب نجوم GitHub وتضيف نطاق fetchGithubStars مخصصًا لتتبع نتيجة طلب الجلب:

import { trace } from '@opentelemetry/api'

export async function fetchGithubStars() {
  return await trace
    .getTracer('nextjs-example')
    .startActiveSpan('fetchGithubStars', async (span) => {
      try {
        return await getValue()
      } finally {
        span.end()
      }
    })
}

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

النطاقات الافتراضية في Next.js

يقوم Next.js تلقائيًا بإعداد عدة نطاقات لتوفير رؤى مفيدة حول أداء التطبيق الخاص بك.

تتبع السمات على النطاقات الاتفاقيات الدلالية لـ OpenTelemetry. نضيف أيضًا بعض السمات المخصصة تحت مساحة الاسم next:

next.span_name - يكرر اسم النطاق
next.span_type - كل نوع نطاق له معرف فريد
next.route - نمط المسار للطلب (مثل /[param]/user).
next.page
- هذه قيمة داخلية تستخدمها موجه التطبيق.
- يمكنك التفكير فيها كمسار لملف خاص (مثل page.ts، layout.ts، loading.ts وغيرها)
- يمكن استخدامها كمعرف فريد فقط عند إقرانها بـ next.route لأن /layout يمكن استخدامها لتحديد كل من /(groupA)/layout.ts و /(groupB)/layout.ts