Personalizza i dati sulle prestazioni con l'API estensibilità

Andrés Olivares

Sofia Emelianova

Panoramica

Vuoi informazioni più dettagliate sul rendimento della tua applicazione oltre alle metriche integrate del browser? Il riquadro Rendimento ora ti consente di inserire i tuoi dati sul rendimento direttamente nella cronologia. Che tu sia un autore di framework che deve visualizzare i processi interni, uno sviluppatore di librerie che monitora l'impatto del codice o che stai creando un'applicazione complessa con strumenti di misurazione personalizzati, l'API di estensione delle prestazioni fornisce gli strumenti per acquisire una conoscenza davvero completa di ciò che accade sotto il cofano.

Inserendo le misurazioni e gli eventi personalizzati, puoi creare visualizzazioni personalizzate nel familiare riquadro Rendimento. Immagina di vedere gli eventi del ciclo di vita dei componenti del tuo framework insieme alle metriche sul rendimento del browser standard o di monitorare il flusso di esecuzione del tuo motore di rendering personalizzato in perfetta sincronia 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 l'instrumentazione delle applicazioni e la visualizzazione dei dati relativi ai tempi esclusivamente nel riquadro Prestazioni in DevTools. È progettato per un overhead di runtime minimo, il che lo rende adatto all'instrumentazione di percorsi caldi e build di produzione. Non aggiunge voci alla cronologia delle prestazioni interne del browser.

2. L'API Tempi utenti (che utilizza performance.mark e performance.measure)

Questa API sfrutta l'API User Timings esistente. Aggiunge inoltre voci alla cronologia delle prestazioni interna del browser, consentendo un'ulteriore analisi e l'integrazione con altri strumenti di misurazione del rendimento.

Vantaggi principali

Entrambe le API offrono:

• Tracce personalizzate:aggiungi tracce e gruppi di tracce dedicati per rappresentare gli aspetti unici del rendimento del tuo codice.
• Voce: compila questi canali con voci che contrassegnino chiaramente gli eventi importanti o la durata di operazioni specifiche.
• Personalizzazione dei colori:utilizza la codifica a colori per distinguere visivamente diversi tipi di eventi o misurazioni a colpo d'occhio.

Scegliere l'API giusta per le tue esigenze:

• API console.timeStamp:

  • L'impatto della misurazione sulle prestazioni è una preoccupazione principale, soprattutto nelle build di produzione.
  • Hai bisogno di un modo rapido ed efficiente per contrassegnare durate o eventi senza la necessità di metadati aggiuntivi.
  • Devi solo visualizzare i dati nel riquadro Rendimento.

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

  • Da utilizzare quando devi archiviare dati aggiuntivi con ogni voce e quando utilizzi già l'API User Timings.
  • Devi associare dati avanzati (descrizioni comando, proprietà dettagliate) alle voci sul rendimento.
  • Vuoi aggiungere indicatori visivi per evidenziare momenti specifici.
  • I dati devono essere disponibili non solo in DevTools, ma anche nella cronologia del rendimento interna del browser per analisi più ampie o altri strumenti.
  • Conosci già o utilizzi l'API User Timings.

Inserisci 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 overhead minimo, in particolare quando DevTools non registra una traccia.

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

• label:

  L'etichetta per la voce relativa alla tempistica.

• (Facoltativo) start:

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

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

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

• end:

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

  • Se definito 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 è definito, viene utilizzata l'ora corrente come ora di fine.

• trackName:

  Il nome del canale personalizzato.

• trackGroup:

  Il nome del gruppo di tracce.

• color:

  Il colore della voce.

Inserire i dati con l'API User Timings

Per inserire dati personalizzati, includi un oggetto devtools nella proprietà detail dei metodi performance.mark e performance.measure. La struttura di questo oggetto devtools determina il modo in cui i dati vengono visualizzati nel riquadro Rendimento.

• 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 di qualsiasi punto d'interesse che non ha una durata. Quando includi un oggetto devtools nella proprietà detail, il riquadro Rendimento mostra un indicatore personalizzato nella traccia Tempi.

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

devtools oggetto

Questi tipi definiscono la struttura dell'oggetto devtools per 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 cronologia

Per visualizzare i dati personalizzati nella sequenza temporale, assicurati che l'impostazione sia attiva nel riquadro Rendimento: settings Impostazioni di acquisizione > check_box Mostra canali personalizzati.

Prova questa pagina demo. Avvia una registrazione del rendimento, fai clic su Aggiungi nuovi corgi nella pagina di demo e poi interrompi la registrazione. Nella traccia viene visualizzato un canale personalizzato contenente eventi con descrizioni comando e dettagli personalizzati nella scheda Riepilogo.

Esempi di codice

Di seguito sono riportati alcuni esempi di come utilizzare l'API per aggiungere i tuoi dati al riquadro Rendimento utilizzando ogni meccanismo disponibile.

console.timeStamp Esempi di API:

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

Di conseguenza, nella cronologia del rendimento viene visualizzata la seguente voce del canale personalizzato:

Esempi di API User Timings:

Nelle sezioni successive, consulta gli esempi di codice che mostrano come aggiungere quanto segue alla cronologia del rendimento:

• Tracce e voci personalizzate nella sequenza temporale
• Indicatori per la traccia Tempi

Canali e voci personalizzati

Crea canali personalizzati e compilali con voci per visualizzare i dati sul rendimento in un canale personalizzato. 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"
    }
  }
});

Il risultato è la seguente voce del canale personalizzato nella cronologia del rendimento, insieme al testo e alle proprietà della descrizione comando:

Indicatori

Evidenzia visivamente punti di interesse specifici nella sequenza temporale con indicatori personalizzati che si estendono su tutti i canali. 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"
    }
  }
});

Il risultato è il seguente indicatore nella traccia Tempi, insieme al testo e alle proprietà della relativa descrizione comando: