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

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

סקירה כללית

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

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

יש שתי דרכים להשתמש ב-API הזה:

1. ‫console.timeStampAPI (מורחב עבור כלי פיתוח)

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

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

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

דוגמה למסלולים בהתאמה אישית בחלונית Performance.

יתרונות עיקריים

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

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

איך לבחור את ה-API שמתאים לצרכים שלכם:

  • console.timeStamp API:

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

  • User Timings API (performance.mark, performance.measure):

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

הזנת נתונים באמצעות console.timeStamp

הרחבנו את ה-API של console.timeStamp כדי לאפשר יצירה של רשומות תזמון בהתאמה אישית בחלונית Performance עם תקורה מינימלית, במיוחד כשכלי הפיתוח לא מתעדים מעקב.

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 מוצג סמן בהתאמה אישית בטראק Timings.

  • אפשר להשתמש ב-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
}

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

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

תיבת הסימון "הצגת טראקים בהתאמה אישית" בקטע "הגדרות תיעוד" בחלונית הביצועים.

אפשר לנסות את התכונה בדף ההדגמה הזה. מתחילים הקלטת ביצועים, לוחצים על Add new Corgi (הוספת קורגי חדש) בדף ההדגמה, ואז מפסיקים את ההקלטה. במעקב יופיע מסלול מותאם אישית שמכיל אירועים עם תיאורי כלים מותאמים אישית, פרטים בכרטיסייה סיכום וסיכומים מותאמים אישית של קבוצות מסלולים בסיכום המעקב.

דוגמאות לקוד

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

דוגמאות ל-API של 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 API.

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

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

סמן בהתאמה אישית בטראק Timings.