Menyesuaikan data performa dengan Extensibility API

Andrés Olivares

Sofia Emelianova

Ringkasan

Panel Performa mendukung API ekstensi performa, yang memungkinkan penambahan data kustom ke linimasa Performa. Hal ini memungkinkan Anda memasukkan pengukuran dan peristiwa secara langsung ke linimasa performa sebagai jalur kustom atau di jalur Pengaturan waktu. Hal ini mungkin berguna bagi developer framework, library, dan aplikasi kompleks dengan instrumentasi kustom untuk mendapatkan pemahaman yang lebih komprehensif tentang performa.

API ini menawarkan dua mekanisme yang berbeda:

1. User Timings API (menggunakan performance.mark dan performance.measure)

API ini memanfaatkan User Timings API yang ada. Alat ini juga menambahkan entri ke linimasa performa internal browser, sehingga memungkinkan analisis lebih lanjut dan integrasi dengan alat performa lainnya.

2. console.timeStamp API (diperluas untuk DevTools)

API ini menyediakan metode berperforma tinggi untuk instrumentasi aplikasi dan menampilkan data pengaturan waktu secara eksklusif ke panel Performa di DevTools. Alat ini dirancang untuk overhead runtime minimal, sehingga cocok untuk instrumentasi jalur panas dan build produksi. Tindakan ini tidak menambahkan entri ke linimasa performa internal browser.

Fitur utama

Kedua API tersebut menawarkan:

• Jalur Kustom: Menambahkan entri ke jalur kustom dan grup jalur.
• Entri: Isi jalur dengan entri yang mewakili peristiwa atau pengukuran.
• Penyesuaian Warna: Entri kode warna untuk diferensiasi visual.

Perbedaan Utama dan kapan harus menggunakan setiap API:

• User Timings API (performance.mark, performance.measure):
  • Menambahkan entri ke panel Performa dan linimasa performa internal browser.
  • Memungkinkan data yang kaya, termasuk tooltip dan properti mendetail.
  • Memungkinkan penambahan penanda: Menandai momen tertentu dalam linimasa dengan penanda visual.
  • Cocok untuk analisis performa mendetail dan jika integrasi dengan alat performa lainnya diperlukan.
  • Gunakan saat Anda perlu menyimpan data tambahan dengan setiap entri, dan saat Anda sudah menggunakan User Timings API.
• console.timeStamp API:
  • Menambahkan entri saja ke panel Performa.
  • Menawarkan performa yang jauh lebih tinggi, terutama di lingkungan produksi.
  • Ideal untuk melakukan instrumentasi pada jalur panas dan kode yang penting untuk performa.
  • Tidak ada data tambahan seperti tooltip atau properti yang dapat ditambahkan.
  • Gunakan jika overhead performa adalah masalah utama, dan Anda perlu membuat instrumen kode dengan cepat.

Memasukkan data Anda dengan User Timings API

Untuk memasukkan data kustom, sertakan objek devtools dalam properti detail dari metode performance.mark dan performance.measure. Struktur objek devtools ini menentukan cara data Anda ditampilkan di panel Performa.

• Gunakan performance.mark untuk merekam peristiwa instan atau stempel waktu di linimasa. Anda dapat menandai awal atau akhir operasi tertentu atau lokasi menarik yang tidak memiliki durasi. Saat Anda menyertakan objek devtools dalam properti detail, panel Performa akan menampilkan penanda kustom di jalur Pengaturan waktu.

• Gunakan performance.measure untuk mengukur durasi tugas atau proses. Saat Anda menyertakan objek devtools dalam properti detail, panel Performa akan menampilkan entri pengukuran kustom di linimasa dalam jalur kustom. Jika menggunakan performance.mark sebagai titik referensi untuk membuat performance.measure, Anda tidak perlu menyertakan objek devtools dalam panggilan performance.mark.

Objek devtools

Jenis ini menentukan struktur objek devtools untuk berbagai fitur ekstensi:

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
}

Memasukkan data dengan console.timeStamp

console.timeStamp API diperluas untuk memungkinkan pembuatan entri pengaturan waktu kustom di panel Performa dengan overhead minimal.

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

• label: Label untuk entri pengaturan waktu.
• start: Nama stempel waktu yang dicatat sebelumnya (menggunakan console.timeStamp(timeStampName)). Jika tidak ditentukan, waktu saat ini akan digunakan.
• end: Nama stempel waktu yang dicatat sebelumnya. Jika tidak ditentukan, waktu saat ini akan digunakan.
• trackName: Nama jalur kustom.
• trackGroup: Nama grup jalur.
• color: Warna entri.

Melihat data Anda di linimasa

Untuk melihat data kustom Anda di linimasa, di panel Performa, aktifkan setelan Setelan pengambilan > kotak centang Data ekstensi.

Coba di halaman demo ini. Aktifkan Data ekstensi, mulai perekaman performa, klik Tambahkan Corgi baru di halaman demo, lalu hentikan perekaman. Anda akan melihat jalur kustom dalam rekaman aktivitas yang berisi peristiwa dengan tooltip dan detail kustom di tab Ringkasan.

Contoh kode

Berikut adalah beberapa contoh cara menggunakan API untuk menambahkan data Anda sendiri ke panel Performa menggunakan setiap mekanisme yang tersedia.

Contoh User Timings API:

Di bagian berikutnya, lihat contoh kode yang menunjukkan cara menambahkan hal berikut ke linimasa performa:

• Trek dan entri kustom ke linimasa
• Penanda ke jalur Waktu

Jalur dan entri kustom

Buat jalur kustom dan isi dengan entri untuk memvisualisasikan data performa Anda di jalur kustom. Contoh:

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

Tindakan ini akan menghasilkan entri jalur kustom berikut di linimasa performa, beserta teks dan properti tooltip-nya:

Penanda

Menandai secara visual lokasi menarik tertentu di linimasa dengan penanda kustom yang mencakup semua jalur. Contoh:

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

Tindakan ini akan menghasilkan penanda berikut di jalur Timings, beserta teks dan properti tooltip-nya:

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

Tindakan ini akan menghasilkan entri jalur kustom berikut di linimasa performa: