Pas uw prestatiegegevens aan met de uitbreidbaarheids-API

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

Overzicht

Het paneel Prestaties ondersteunt de API voor prestatie-uitbreiding, waardoor aangepaste gegevens aan de prestatietijdlijn kunnen worden toegevoegd. Hierdoor kunt u uw metingen en gebeurtenissen rechtstreeks in de prestatietijdlijn injecteren als een aangepaste track of in de Timings -track. Dit kan nuttig zijn voor ontwikkelaars van raamwerken, bibliotheken en complexe applicaties met aangepaste instrumenten om een ​​uitgebreider inzicht in de prestaties te krijgen.

Deze API biedt twee verschillende mechanismen:

1. De User Timings API (met behulp van performance.mark en performance.measure )

Deze API maakt gebruik van de bestaande User Timings API . Het voegt ook vermeldingen toe aan de interne prestatietijdlijn van de browser, waardoor verdere analyse en integratie met andere prestatietools mogelijk is.

2. De console.timeStamp API (uitgebreid voor DevTools)

Deze API biedt een krachtige methode voor het instrumenteren van toepassingen en het weergeven van timinggegevens exclusief in het prestatiepaneel in DevTools. Het is ontworpen voor minimale runtime-overhead, waardoor het geschikt is voor het instrumenteren van hot paths en productiebuilds. Het voegt geen gegevens toe aan de interne prestatietijdlijn van de browser.

Belangrijkste kenmerken

Beide API's bieden:

  • Aangepaste tracks: Voeg items toe aan aangepaste tracks en trackgroepen.
  • Invoer : vul tracks in met vermeldingen die gebeurtenissen of metingen vertegenwoordigen.
  • Kleuraanpassing: Kleurcode-invoer voor visuele differentiatie.

Belangrijkste verschillen en wanneer elke API moet worden gebruikt:

  • API voor gebruikerstiming ( performance.mark , performance.measure ):
    • Voegt vermeldingen toe aan zowel het prestatiepaneel als de interne prestatietijdlijn van de browser.
    • Maakt rijke gegevens mogelijk, inclusief tooltips en gedetailleerde eigenschappen.
    • Maakt het toevoegen van markeringen mogelijk: Markeer specifieke momenten in de tijdlijn met visuele markeringen.
    • Geschikt voor gedetailleerde prestatieanalyse en wanneer integratie met andere prestatietools vereist is.
    • Gebruik dit wanneer u bij elke invoer extra gegevens moet opslaan en wanneer u de User Timings API al gebruikt.
  • console.timeStamp -API:
    • Voegt alleen items toe aan het paneel Prestaties .
    • Biedt aanzienlijk hogere prestaties, vooral in productieomgevingen.
    • Ideaal voor het instrumenteren van hotpaths en prestatiekritieke code.
    • Er kunnen geen extra gegevens zoals tooltips of eigenschappen worden toegevoegd.
    • Gebruik dit wanneer prestatieoverhead een primaire zorg is en u snel code moet instrumenteren.

Injecteer uw gegevens met de User Timings API

Als u aangepaste gegevens wilt injecteren, neemt u een devtools -object op in de eigenschap detail van de methoden performance.mark en performance.measure . De structuur van dit devtools -object bepaalt hoe uw gegevens worden weergegeven in het paneel Prestaties .

  • Gebruik performance.mark om een ​​directe gebeurtenis of tijdstempel in de tijdlijn op te nemen. U kunt het begin of einde van een specifieke operatie of een interessant punt zonder duur markeren. Wanneer u een devtools -object opneemt in de detail , toont het paneel Prestaties een aangepaste markering in de timingtrack .

  • Gebruik performance.measure om de duur van een taak of proces te meten. Wanneer u een devtools -object opneemt in de detail , worden in het deelvenster Prestaties aangepaste meetgegevens weergegeven in de tijdlijn in een aangepast spoor. Als u performance.mark als referentiepunt gebruikt om een performance.measure te maken, hoeft u het devtools object niet op te nemen in performance.mark -aanroepen.

devtools -object

Deze typen definiëren de structuur van het devtools -object voor verschillende uitbreidingsfuncties:

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
}

Injecteer uw gegevens met console.timeStamp

De console.timeStamp API is uitgebreid om het maken van aangepaste timing-items in het Prestatiepaneel mogelijk te maken met minimale overhead.

console.timeStamp(label: string, start?: string, end?: string, trackName?: string, trackGroup?: string, color?: DevToolsColor);
  • label : Het label voor de timinginvoer.
  • start : De naam van een eerder opgenomen tijdstempel (met behulp van console.timeStamp(timeStampName) ). Indien niet gedefinieerd, wordt de huidige tijd gebruikt.
  • end : De naam van een eerder opgenomen tijdstempel. Indien niet gedefinieerd, wordt de huidige tijd gebruikt.
  • trackName : De naam van de aangepaste track.
  • trackGroup : De naam van de trackgroep.
  • color : De kleur van het item.

Bekijk uw gegevens in de tijdlijn

Als u uw aangepaste gegevens in de tijdlijn wilt zien, schakelt u in het paneel Prestaties Instellingen vastleggen > Extensiegegevens in.

Het selectievakje 'Extensiegegevens' in de 'Opname-instellingen' van het paneel Prestaties.

Probeer het op deze demopagina . Schakel Extensiegegevens in, start een uitvoeringsopname, klik op Nieuwe Corgi toevoegen op de demopagina en stop vervolgens de opname. U ziet een aangepaste track in de trace die gebeurtenissen bevat met aangepaste knopinfo en details op het tabblad Samenvatting .

Codevoorbeelden

Hier volgen enkele voorbeelden van hoe u de API kunt gebruiken om uw eigen gegevens toe te voegen aan het prestatiepaneel met behulp van elk beschikbaar mechanisme.

API-voorbeelden voor gebruikerstiming:

In de volgende secties ziet u de codevoorbeelden die laten zien hoe u het volgende aan de prestatietijdlijn kunt toevoegen:

Aangepaste nummers en vermeldingen

Maak aangepaste tracks en vul deze met vermeldingen om uw prestatiegegevens in een aangepaste track te visualiseren. Bijvoorbeeld:

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

Dit resulteert in de volgende aangepaste trackinvoer in de prestatietijdlijn, samen met de bijbehorende tooltiptekst en eigenschappen:

Een aangepaste track in de prestatietijdlijn.

Markeringen

Markeer visueel specifieke aandachtspunten in de tijdlijn met aangepaste markeringen die zich over alle tracks uitstrekken. Bijvoorbeeld:

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

Dit resulteert in de volgende markering in het timingspoor , samen met de tooltiptekst en eigenschappen:

Een aangepaste markering in de timingtrack.

console.timeStamp API-voorbeelden:

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

Dit resulteert in de volgende aangepaste trackinvoer in de prestatietijdlijn:

Een aangepaste track met aangepaste vermeldingen toegevoegd met de console.timeStamp API.