Personalizza i dati sulle prestazioni con l'API estensibilità

Andrés Olivares

Sofia Emelianova

Panoramica

Vuoi informazioni più approfondite sul rendimento della tua applicazione oltre alle metriche integrate del browser? Il riquadro Prestazioni ti consente ora di inserire i tuoi dati sul rendimento direttamente nella sequenza temporale. Che tu sia un autore di framework che ha bisogno di visualizzare i processi interni, uno sviluppatore di librerie che monitora l'impatto del tuo codice o che stia creando un'applicazione complessa con strumentazione personalizzata, l'API di estensibilità delle prestazioni fornisce gli strumenti per ottenere una comprensione davvero completa di ciò che accade dietro le quinte.

Inserendo le tue misurazioni ed eventi personalizzati, puoi creare visualizzazioni personalizzate all'interno del riquadro Prestazioni che già conosci. Immagina di vedere gli eventi del ciclo di vita dei componenti del tuo framework insieme alle metriche standard sul rendimento del browser o di monitorare il flusso di esecuzione del tuo motore di rendering personalizzato in perfetta sincronizzazione con la pipeline di rendering del browser.

Questa API offre due approcci per raggiungere questo obiettivo:

1. L'API console.timeStamp (estesa per DevTools)

Questa API fornisce un metodo ad alte prestazioni per strumentare le applicazioni e visualizzare i dati di temporizzazione esclusivamente nel riquadro Prestazioni in DevTools. È progettata per un sovraccarico di runtime minimo, il che la rende adatta per strumentare i percorsi attivi e le build di produzione. Non aggiunge voci alla sequenza temporale delle prestazioni interne del browser.

2. L'API User Timings (utilizzando performance.mark e performance.measure)

Questa API sfrutta l'API User Timings esistente. Aggiunge anche voci alla sequenza temporale delle prestazioni interne del browser, consentendo un'ulteriore analisi e integrazione con altri strumenti per le prestazioni.

Vantaggi principali

Entrambe le API offrono:

• Tracce personalizzate: aggiungi tracce e gruppi di tracce dedicati per rappresentare gli aspetti unici delle prestazioni del tuo codice.
• Voci: popola queste tracce con voci che contrassegnano chiaramente gli eventi importanti o la durata di un'operazione specifica.
• Personalizzazione dei colori: utilizza la codifica per colore per distinguere visivamente i diversi tipi di eventi o misurazioni a colpo d'occhio.

Scegliere l'API giusta per le tue esigenze:

• API console.timeStamp:

  • L'impatto sulle prestazioni della strumentazione è una preoccupazione primaria, soprattutto nelle build di produzione.
  • Hai bisogno di un modo rapido ed efficiente per contrassegnare durate o eventi senza la necessità di metadati aggiuntivi.
  • Hai bisogno che i dati vengano visualizzati solo nel riquadro Prestazioni.

• API Tempi utente (performance.mark, performance.measure):

  • Utilizza questa API quando devi memorizzare dati aggiuntivi con ogni voce e quando utilizzi già l'API User Timings.
  • Devi associare informazioni aggiuntive (suggerimenti, proprietà dettagliate) alle voci relative alle prestazioni.
  • Vuoi aggiungere indicatori visivi per evidenziare momenti specifici.
  • Hai bisogno che i dati siano disponibili non solo in DevTools, ma anche nella sequenza temporale delle prestazioni interne del browser per un'analisi più ampia o altri strumenti.
  • Conosci o utilizzi già l'API Tempi utente.

Inserire i dati con console.timeStamp

L'API console.timeStamp è stata estesa per consentire la creazione di voci di temporizzazione personalizzate nel riquadro Prestazioni con un sovraccarico minimo, soprattutto quando DevTools non sta registrando una traccia.

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

• label:

  L'etichetta per la voce di temporizzazione.

• start (facoltativo):

  • Se definita come stringa: il nome di un timestamp registrato in precedenza (utilizzando console.timeStamp(timeStampName)).

  • Se definita come numero: un timestamp in millisecondi relativo a Performance.timeOrigin (ad esempio, acquisito con performance.now()) che rappresenta l'ora di inizio della voce di temporizzazione.

  • Se non è definita, viene utilizzata l'ora corrente come ora di inizio.

• end:

  • Se definita come stringa: il nome di un timestamp registrato in precedenza.

  • Se definita come numero: un timestamp in millisecondi relativo a Performance.timeOrigin (ad esempio, acquisito con performance.now()) che rappresenta l'ora di fine della voce di temporizzazione.

  • Se non è definita, viene utilizzata l'ora corrente come ora di fine.

• trackName:

  Il nome della traccia personalizzata.

• trackGroup:

  Il nome del gruppo di tracce.

• color:

  Il colore della voce.

Inserire i dati con l'API Tempi utente

Per inserire dati personalizzati, includi un devtools oggetto nella proprietà detail dei metodi performance.mark e performance.measure. La struttura di questo oggetto devtools determina la modalità di visualizzazione dei dati nel riquadro Prestazioni.

• Utilizza performance.mark per registrare un evento istantaneo o un timestamp nella sequenza temporale. Puoi contrassegnare l'inizio o la fine di un'operazione specifica o qualsiasi punto di interesse che non abbia una durata. Quando includi un oggetto devtools nella proprietà detail, il riquadro Prestazioni mostra un indicatore personalizzato nella traccia Temporizzazioni.

• Utilizza performance.measure per misurare la durata di un'attività o di un processo. Quando includi un oggetto devtools nella proprietà detail, il riquadro Prestazioni mostra le voci di misurazione personalizzate nella sequenza temporale in una traccia personalizzata. Se utilizzi performance.mark come punto di riferimento per creare un performance.measure, non devi includere l'oggetto devtools nelle chiamate performance.mark.

Oggetto devtools

Questi tipi definiscono la struttura dell'oggetto devtools per le diverse funzionalità di estensione:

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
}

Visualizzare i dati nella sequenza temporale

Per visualizzare i dati personalizzati nella sequenza temporale, nel riquadro Prestazioni assicurati che l'impostazione sia attiva: impostazioni Impostazioni di acquisizione > check_box Mostra tracce personalizzate.

Prova questa pagina demo. Avvia una registrazione delle prestazioni, fai clic su Aggiungi nuovo Corgi nella pagina demo, quindi interrompi la registrazione. Nella traccia vedrai una traccia personalizzata che contiene eventi con suggerimenti personalizzati, dettagli nella scheda Riepilogo e riepiloghi di gruppi di tracce personalizzati nel riepilogo della traccia.

Esempi di codice

Ecco alcuni esempi di come utilizzare l'API per aggiungere i tuoi dati al riquadro Prestazioni utilizzando ciascun meccanismo disponibile.

Esempi di 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");

Viene visualizzata la seguente voce di traccia personalizzata nella sequenza temporale delle prestazioni:

Esempi di API Tempi utente:

Nelle sezioni successive, consulta gli esempi di codice che mostrano come aggiungere quanto segue alla sequenza temporale delle prestazioni:

• Tracce e voci personalizzate nella sequenza temporale
• Indicatori nella traccia Temporizzazioni

Tracce e voci personalizzate

Crea tracce personalizzate e popola le voci per visualizzare i dati sul rendimento in una traccia personalizzata. Ad esempio:

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

Viene visualizzata la seguente voce di traccia personalizzata nella sequenza temporale delle prestazioni, insieme al testo del suggerimento e alle proprietà:

Indicatori

Evidenzia visivamente punti di interesse specifici nella sequenza temporale con indicatori personalizzati che si estendono su tutte le tracce. Ad esempio:

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

Viene visualizzato il seguente indicatore nella traccia Temporizzazioni, insieme al testo del suggerimento e alle proprietà: