تخصيص بيانات الأداء باستخدام واجهة برمجة التطبيقات القابلة للتوسّع

Andrés Olivares

Sofia Emelianova

نظرة عامة

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

توفّر واجهة برمجة التطبيقات هذه آليتين مختلفتَين:

1. User Timings API (باستخدام performance.mark وperformance.measure)

تستفيد واجهة برمجة التطبيقات هذه من واجهة User Timings API الحالية. وتضيف هذه الميزة أيضًا إدخالات إلىالمخطط الزمني الداخلي للأداء في المتصفّح، ما يتيح إجراء المزيد من التحليل والدمج مع أدوات الأداء الأخرى.

2- واجهة برمجة تطبيقات console.timeStamp (الموسّعة لخدمة DevTools)

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

الميزات الرئيسية

توفّر كلتا واجهات برمجة التطبيقات ما يلي:

• المسارات المخصّصة: يمكنك إضافة إدخالات إلى المسارات المخصّصة ومجموعات المسارات.
• الإدخالات: يمكنك تعبئة مسارات الاختبار بإدخالات تمثّل الأحداث أو القياسات.
• تخصيص الألوان: إدخالات الرموز اللونية للتمييز المرئي

الاختلافات الرئيسية وحالات استخدام كل واجهة برمجة تطبيقات:

• User Timings API (performance.mark, performance.measure):
  • تُضيف إدخالات إلى كلّ من لوحة الأداء والمخطط الزمني الداخلي للأداء في المتصفّح.
  • السماح بعرض بيانات غنية، بما في ذلك معلومات توضيحية والسمات التفصيلية
  • السماح بإضافة العلامات: يمكنك تمييز لحظات معيّنة في المخطط الزمني باستخدام علامات مرئية.
  • مناسبة لتحليل الأداء التفصيلي وعند الحاجة إلى الدمج مع أدوات الأداء الأخرى
  • استخدِم هذا الإجراء عندما تحتاج إلى تخزين بيانات إضافية مع كل إدخال، وعندما تكون تستخدِم User Timings API.
• console.timeStamp API:
  • تُضيف الإدخالات فقط إلى لوحة الأداء.
  • يوفّر أداءً أعلى بكثير، خاصةً في بيئات الإنتاج.
  • مثالية لقياس مسارات التنفيذ الشائعة والرمز البرمجي المهم للأداء
  • ولا يمكن إضافة أي بيانات إضافية، مثل التلميحات أو السمات.
  • استخدِم هذا الخيار عندما يكون عبء الأداء هو مصدر القلق الأساسي، وتحتاج إلى قياس أداء الرمز البرمجي بسرعة.

إدخال بياناتك باستخدام User Timings API

لإدخال بيانات مخصّصة، أدرِج عنصر devtools ضمن سمة detail لطُرق performance.mark وperformance.measure. تحدّد بنية عنصر devtools هذا كيفية عرض بياناتك في لوحة الأداء.

• استخدِم performance.mark لتسجيل حدث فوري أو طابع زمني في المخطط الزمني. يمكنك وضع علامة على بداية أو نهاية عملية معيّنة أو أي نقطة اهتمام لا تتضمّن مدة. عند تضمين عنصر devtools ضمن عنصر detail، تعرِض لوحة الأداء علامة مخصّصة في مسار المواعيد.

• استخدِم performance.measure لقياس مدة مهمة أو عملية. عند تضمين عنصر devtools ضمن detail، تعرض لوحة الأداء إدخالات قياس مخصّصة في المخطط الزمني ضمن مسار مخصّص. إذا كنت تستخدم performance.mark كنقطة مرجعية لإنشاء performance.measure، ليس عليك تضمين العنصر devtools في طلبات performance.mark.

عنصر devtools

تحدِّد هذه الأنواع بنية عنصر devtools لميزات الإضافة المختلفة:

type DevToolsColor =
  "primary" | "primary-light" | "primary-dark" |
  "secondary" | "secondary-light" | "secondary-dark" |
  "tertiary" | "tertiary-light" | "tertiary-dark" |
  "error";

interface ExtensionTrackEntryPayload {
  dataType?: "track-entry"; // Defaults to "track-entry"
  color?: DevToolsColor;    // Defaults to "primary"
  track: string;            // Required: Name of the custom track
  trackGroup?: string;      // Optional: Group for organizing tracks
  properties?: [string, string][]; // Key-value pairs for detailed view
  tooltipText?: string;     // Short description for tooltip
}

interface ExtensionMarkerPayload {
  dataType: "marker";       // Required: Identifies as a marker
  color?: DevToolsColor;    // Defaults to "primary"
  properties?: [string, string][]; // Key-value pairs for detailed view
  tooltipText?: string;     // Short description for tooltip
}

إدراج بياناتك باستخدام console.timeStamp

تمّت توسيع نطاق واجهة برمجة التطبيقات console.timeStamp للسماح بإنشاء إدخالات توقيت مخصّصة في لوحة الأداء بأقلّ قدر ممكن من التكاليف.

console.timeStamp(label: string, start?: string, end?: string, trackName?: string, trackGroup?: string, color?: DevToolsColor);

• label: تصنيف إدخال التوقيت
• start: اسم طابع زمني تم تسجيله سابقًا (باستخدام console.timeStamp(timeStampName)). إذا لم يتم تحديده، يتم استخدام الوقت الحالي.
• ‫end: اسم طابع زمني تم تسجيله سابقًا. وفي حال عدم تحديدها، يتم استخدام الوقت الحالي.
• trackName: اسم المسار المخصّص
• trackGroup: اسم مجموعة المقاطع الصوتية
• ‫color: لون الإدخال

عرض بياناتك في المخطط الزمني

للاطّلاع على بياناتك المخصّصة في المخطط الزمني، فعِّل الإعدادات إعدادات الالتقاط > مربّع الاختيار بيانات الإضافة في لوحة الأداء.

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

أمثلة على الرموز البرمجية

في ما يلي بعض الأمثلة على كيفية استخدام واجهة برمجة التطبيقات لإضافة بياناتك إلى لوحة الأداء باستخدام كل آلية متاحة.

أمثلة على User Timings API:

في الأقسام التالية، يمكنك الاطّلاع على أمثلة على الرموز البرمجية التي توضّح كيفية إضافة ما يلي إلى المخطط الزمني للأداء:

• إضافة مسارات وإدخالات مخصّصة إلى المخطط الزمني
• إضافة علامات إلى مسار "التوقيتات"

القنوات والتسجيلات المخصّصة

أنشئ مسارات مخصّصة واملأها بإدخالات لعرض بيانات الأداء في مسار مخصّص. على سبيل المثال:

// Mark used to represent the start of the image processing task
// The start time is defaulted to now
performance.mark("Image Processing Start");

// ... later in your code

// Track entry representing the completion of image processing
// with additional details and a tooltip
// The start time is a marker from earlier
// The end time is defaulted to now
performance.measure("Image Processing Complete", {
  start: "Image Processing Start",
  detail: {
    devtools: {
      dataType: "track-entry",
      track: "Image Processing Tasks",
      trackGroup: "My Tracks", // Group related tracks together
      color: "tertiary-dark",
      properties: [
        ["Filter Type", "Gaussian Blur"],
        ["Resize Dimensions", "500x300"]
      ],
      tooltipText: "Image processed successfully"
    }
  }
});

يؤدّي ذلك إلى إدراج المسار المخصّص التالي في المخطط الزمني للأداء، بالإضافة إلى نص التلميح وخصائصه:

العلامات

يمكنك تمييز نقاط اهتمام معيّنة في المخطط الزمني باستخدام علامات مخصّصة على جميع المقاطع الصوتية. على سبيل المثال:

// Marker indicating when the processed image was uploaded
performance.mark("Image Upload", {
  detail: {
    devtools: {
      dataType: "marker",
      color: "secondary",
      properties: [
        ["Image Size", "2.5MB"],
        ["Upload Destination", "Cloud Storage"]
      ],
      tooltipText: "Processed image uploaded"
    }
  }
});

يؤدي ذلك إلى ظهور العلامة التالية في مقطع المواقيت، بالإضافة إلى نص التلميح وخصائصه:

console.timeStamp أمثلة على واجهات برمجة التطبيقات:

// Record a start timestamp
console.timeStamp("start");

// Measure duration from start to now
console.timeStamp("measure 1", "start", undefined, "My Track", "My Group", "primary-light");

// Record an end timestamp
console.timeStamp("end");

// Measure duration from start to end
console.timeStamp("measure 2", "start", "end", "My Track", "My Group", "secondary-dark");

يؤدّي ذلك إلى إدخال المسار المخصّص التالي في مخطط الأداء الزمني: