התאמה אישית של נתוני הביצועים באמצעות API להרחבה

Andrés Olivares

Sofia Emelianova

סקירה כללית

בחלונית ביצועים יש תמיכה ב-API להרחבת הביצועים, שמאפשר להוסיף נתונים מותאמים אישית לציר הזמן של הביצועים. כך תוכלו להוסיף את המדידות והאירועים ישירות לציר הזמן של הביצועים כטראק מותאם אישית או כטראק Timings. האפשרות הזו עשויה להיות שימושית למפתחים של מסגרות, ספריות ואפליקציות מורכבות עם מכשירי מדידה מותאמים אישית, כדי לקבל תמונה מקיפה יותר של הביצועים.

ה-API הזה מציע שני מנגנונים נפרדים:

1. User Timings API (באמצעות performance.mark ו-performance.measure)

ה-API הזה מבוסס על User Timings API הקיים. הוא גם מוסיף רשומות לציר הזמן הפנימי של הביצועים בדפדפן, ומאפשר ניתוח נוסף ושילוב עם כלים אחרים לבדיקת ביצועים.

2. ממשק ה-API של console.timeStamp (מורחב ל-DevTools)

ממשק ה-API הזה מספק שיטה בעלת ביצועים משופרים להטמעת רכיבים באפליקציות ולהצגת נתוני תזמון באופן בלעדי בחלונית ביצועים ב-DevTools. הוא תוכנן כך שיהיה לו מינימום תקורה בסביבת זמן הריצה, ולכן הוא מתאים לכלי למדידת ביצועים של נתיבים חמים ובניינים לייצור. הוא לא מוסיף רשומות לציר הזמן הפנימי של הביצועים בדפדפן.

תכונות עיקריות

שני ממשקי ה-API מציעים:

• טראקים מותאמים אישית: הוספת רשומות לטראקים ולקבוצות של טראקים בהתאמה אישית.
• רשומות: מאכלסים את הטראקים ברשומות שמייצגות אירועים או מדידות.
• התאמה אישית של צבעים: סימון רשומות בקוד צבע לצורך הבחנה חזותית.

הבדלים עיקריים ומתי כדאי להשתמש בכל API:

• 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

ממשק ה-API 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: הצבע של הרשומה.

הצגת הנתונים בציר הזמן

כדי לראות את הנתונים המותאמים אישית בציר הזמן, בחלונית ביצועים מפעילים את הגדרות הגדרות הצילום > תיבת סימון נתוני התוסף.

אפשר לנסות את זה בדף הדגמה הזה. מפעילים את האפשרות נתוני התוסף, מתחילים להקליט את הביצועים, לוחצים על הוספת כלב קורג'י חדש בדף הדגמה ומפסיקים את ההקלטה. בכרטיסייה Summary יופיע מסלול מותאם אישית במעקב, שמכיל אירועים עם טיפים מותאמים אישית ופרטים.

דוגמאות לקוד

ריכזנו כאן כמה דוגמאות לאופן שבו אפשר להשתמש ב-API כדי להוסיף נתונים משלכם לחלונית ביצועים באמצעות כל מנגנון זמין.

דוגמאות ל-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"
    }
  }
});

הפעולה הזו יוצרת את הסמן הבא בטראק Timings, יחד עם הטקסט והמאפיינים של תיאור המיקום:

console.timeStamp דוגמאות ל-API:

// 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");

כתוצאה מכך, תופיע הרשומה הבאה של הטראק בהתאמה אישית בציר הזמן של הביצועים: