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

Andrés Olivares
Andrés Olivares
X GitHub
Sofia Emelianova
Sofia Emelianova
GitHub

نظرة عامة

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

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

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

1. واجهة برمجة التطبيقات console.timeStamp (تمت إضافة وظائف إليها لتتوافق مع "أدوات مطوّري البرامج")

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

2. واجهة برمجة التطبيقات User Timings API (باستخدام performance.mark وperformance.measure)

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

مثال على شكل المسارات المخصّصة في لوحة "الأداء"

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

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

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

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

  • واجهة برمجة التطبيقات console.timeStamp:

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

  • واجهة برمجة التطبيقات User Timings API (performance.mark، performance.measure):

    • استخدِم هذه الطريقة عندما تحتاج إلى تخزين بيانات إضافية مع كل إدخال، وعندما تكون قد استخدمت User Timings API.
    • يجب ربط البيانات الغنية (تلميحات الأدوات والسمات التفصيلية) بإدخالات الأداء.
    • تريد إضافة علامات مرئية لتسليط الضوء على لحظات معيّنة.
    • تحتاج إلى أن تكون البيانات متاحة ليس فقط في "أدوات مطوري البرامج"، بل أيضًا في المخطط الزمني الداخلي للأداء في المتصفّح لإجراء تحليل أوسع أو استخدام أدوات أخرى.
    • أنّك على دراية بواجهة برمجة التطبيقات User Timings API أو تستخدمها.

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

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

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

  • label:

    تمثّل هذه المَعلمة تصنيف إدخال التوقيت.

  • start (اختياري):

    • إذا تم تحديدها كسلسلة: اسم طابع زمني تم تسجيله سابقًا (باستخدام console.timeStamp(timeStampName)).

    • إذا تم تحديدها كرقم: طابع زمني بالملي ثانية مرتبط بـ Performance.timeOrigin (على سبيل المثال، تم الحصول عليه باستخدام performance.now()) يمثّل وقت بدء إدخال التوقيت.

    • إذا لم يتم تحديدها، يتم استخدام الوقت الحالي كوقت بدء.

  • end:

    • إذا تم تحديده كسلسلة: اسم طابع زمني تم تسجيله سابقًا.

    • إذا تم تحديدها كرقم: طابع زمني بالملّي ثانية بالنسبة إلى Performance.timeOrigin (على سبيل المثال، تم الحصول عليه باستخدام performance.now()) ويمثّل وقت انتهاء إدخال التوقيت.

    • في حال عدم تحديد وقت الانتهاء، يتم استخدام الوقت الحالي.

  • trackName:

    اسم المسار المخصّص

  • trackGroup:

    اسم مجموعة المقاطع الصوتية

  • color:

    لون الإدخال

إدخال بياناتك باستخدام 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
}

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

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

مربّع الاختيار "عرض المسارات المخصّصة" في "إعدادات التسجيل" ضمن لوحة "الأداء"

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

أمثلة على الرموز

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

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

// Take a start timestamp
const start = performance.now();

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

// Take an end timestamp
const end = performance.now();

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

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

مسار مخصّص مع إدخالات مخصّصة تمت إضافتها باستخدام واجهة برمجة التطبيقات console.timeStamp.

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

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

قنوات الإصدار المخصّصة وإدخالاتها

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

// Mark used to represent the start of the image processing task
// The start time is defaulted to now
const imageProcessinTimeStart = performance.now();

// ... 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: imageProcessinTimeStart,
  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"
    }
  }
});

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

علامة مخصّصة في مسار "التوقيتات"