Personalizza i dati sulle prestazioni con l'API estensibilità

Andrés Olivares
Andrés Olivares
Sofia Emelianova
Sofia Emelianova

Panoramica

Il riquadro Rendimento supporta l'API di estensioni del rendimento, che consente di aggiungere dati personalizzati alla cronologia del rendimento. In questo modo puoi inserire le misurazioni e gli eventi direttamente nella sequenza temporale del rendimento come traccia personalizzata o nella traccia Tempi. Ciò può essere utile per gli sviluppatori di framework, librerie e applicazioni complesse con strumenti di misurazione personalizzati per ottenere una comprensione più completa delle prestazioni.

Questa API offre due meccanismi distinti:

1. 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.

2. 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.

Funzionalità principali

Entrambe le API offrono:

  • Canali personalizzati:aggiungi voci a canali e gruppi di canali personalizzati.
  • Voce: compila i canali con voci che rappresentano eventi o misurazioni.
  • Personalizzazione dei colori:inserisci codici colore per la differenziazione visiva.

Differenze principali e quando utilizzare ciascuna API:

  • API User Timings (performance.mark, performance.measure):
    • Aggiunge voci sia al riquadro Rendimento che alla cronologia del rendimento interno del browser.
    • Consente dati completi, tra cui descrizioni comando e proprietà dettagliate.
    • Consente di aggiungere indicatori: evidenzia momenti specifici della cronologia con indicatori visivi.
    • Adatta per l'analisi dettagliata del rendimento e quando è richiesta l'integrazione con altri strumenti di misurazione del rendimento.
    • Da utilizzare quando devi archiviare dati aggiuntivi con ogni voce e quando utilizzi già l'API User Timings.
  • API console.timeStamp:
    • Aggiunge voci solo al riquadro Rendimento.
    • Offre prestazioni notevolmente superiori, in particolare negli ambienti di produzione.
    • Ideale per l'instrumentazione di percorsi caldi e codice critico per le prestazioni.
    • Non è possibile aggiungere dati aggiuntivi come descrizioni comando o proprietà.
    • Da utilizzare quando l'overhead delle prestazioni è una preoccupazione principale e devi eseguire rapidamente l'instrumentazione del codice.

Inserire i dati con l'API User Timings

Per inserire dati personalizzati, includi un oggetto devtools all'interno della 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
}

Inserisci i dati con console.timeStamp

L'API console.timeStamp è stata estesa per consentire la creazione di voci di temporizzazione personalizzate nel riquadro Rendimento con un overhead minimo.

console.timeStamp(label: string, start?: string, end?: string, trackName?: string, trackGroup?: string, color?: DevToolsColor);
  • label: l'etichetta per la voce relativa ai tempi.
  • start: il nome di un timestamp registrato in precedenza (utilizzando console.timeStamp(timeStampName)). Se non è definito, viene utilizzata l'ora corrente.
  • end: il nome di un timestamp registrato in precedenza. Se non è definito, viene utilizzato l'ora corrente.
  • trackName: il nome della traccia personalizzata.
  • trackGroup: il nome del gruppo di tracce.
  • color: il colore della voce.

Visualizzare i dati nella cronologia

Per visualizzare i dati personalizzati nella sequenza temporale, nel riquadro Rendimento attiva Impostazioni di acquisizione > Dati dell'estensione.

La casella di controllo "Dati delle estensioni" in "Impostazioni di acquisizione" del riquadro Rendimento.

Prova questa pagina demo. Attiva Dati delle estensioni, avvia una registrazione del rendimento, fai clic su Aggiungi nuovi corgi nella pagina di dimostrazione 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.

Esempi di API User Timings:

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

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

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

Un canale personalizzato nella sequenza temporale del rendimento.

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:

Un indicatore personalizzato nel canale Tempi.

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

Il risultato è la seguente voce della traccia personalizzata nella cronologia del rendimento:

Un canale personalizzato con voci personalizzate aggiunte con l'API console.timeStamp.