Je prestatiegegevens aanpassen met de uitbreidbaarheids-API

Andrés Olivares

Sofia Emelianova

Overzicht

Wilt u meer inzicht in de prestaties van uw app dan de ingebouwde statistieken van de browser? Met het deelvenster Prestaties kunt u nu uw eigen prestatiegegevens rechtstreeks in de tijdlijn invoegen. Of u nu een frameworkauteur bent die interne processen wil visualiseren, een bibliotheekontwikkelaar die de impact van uw code bijhoudt of een complexe app met aangepaste instrumentatie bouwt, de API voor prestatie-uitbreidbaarheid biedt de tools om een echt uitgebreid inzicht te krijgen in wat er onder de motorkap gebeurt.

Door uw aangepaste metingen en gebeurtenissen te injecteren, kunt u aangepaste visualisaties maken in het vertrouwde deelvenster Prestaties. Stel u voor dat u de levenscyclusgebeurtenissen van de componenten van uw framework ziet naast de standaard prestatiestatistieken van de browser of dat u de uitvoeringsstroom van uw gepersonaliseerde weergave-engine perfect synchroon met de weergavepijplijn van de browser bijhoudt.

Deze API biedt 2 manieren om dit te doen:

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

Deze API biedt een hoogwaardige methode om apps te instrumenteren en timinggegevens uitsluitend te tonen in het deelvenster Prestaties in DevTools. De API is ontworpen voor minimale runtime-overhead, waardoor deze geschikt is voor het instrumenteren van hot paths en productieversies. Er worden geen vermeldingen toegevoegd aan de interne prestatie-tijdlijn van de browser.

2. De API voor gebruikerstiming (met performance.mark en performance.measure)

Deze API maakt gebruik van de bestaande API voor gebruikerstiming. Er worden ook vermeldingen toegevoegd aan de interne prestatie-tijdlijn van de browser, zodat u verdere analyses kunt uitvoeren en de API kunt integreren met andere prestatietools.

Belangrijkste voordelen

Beide API's bieden het volgende:

• Aangepaste tracks: Voeg speciale tracks en trackgroepen toe om de unieke prestatieaspecten van uw code voor te stellen.
• Vermeldingen: Vul deze tracks in met vermeldingen die belangrijke gebeurtenissen of de duur van een specifieke bewerking duidelijk markeren.
• Kleuraanpassing: Gebruik kleurcodering om verschillende typen gebeurtenissen of metingen in één oogopslag visueel te onderscheiden.

De juiste API voor uw behoeften kiezen:

• API console.timeStamp:

  • De prestatie-impact van instrumentatie is een primaire zorg, vooral in productieversies.
  • U heeft een snelle en efficiënte manier nodig om duur of gebeurtenissen te markeren zonder dat u extra metadata nodig heeft.
  • U wilt de gegevens alleen visualiseren in het deelvenster Prestaties.

• API voor gebruikerstiming (performance.mark, performance.measure):

  • Gebruik deze API als u extra gegevens bij elke vermelding wilt opslaan en als u de API voor gebruikerstiming al gebruikt.
  • U wilt uitgebreide gegevens (tooltips, gedetailleerde property's) koppelen aan uw prestatievermeldingen.
  • U wilt visuele markeringen toevoegen om specifieke momenten te markeren.
  • U wilt dat de gegevens niet alleen beschikbaar zijn in DevTools, maar ook in de interne prestatie-tijdlijn van de browser voor bredere analyse of andere tools.
  • U bent al bekend met de API voor gebruikerstiming of gebruikt deze al.

Uw gegevens injecteren met console.timeStamp

De API console.timeStamp is uitgebreid om de creatie van aangepaste timingvermeldingen in het deelvenster Prestaties mogelijk te maken met minimale overhead, vooral als DevTools geen trace opneemt.

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

• label:

  Het label voor de timingvermelding.

• start (optioneel):

  • Als deze is gedefinieerd als tekenreeks: de naam van een eerder opgenomen tijdstempel (met console.timeStamp(timeStampName)).

  • Als deze is gedefinieerd als getal: een tijdstempel in milliseconden ten opzichte van Performance.timeOrigin (bijvoorbeeld genomen met performance.now()) dat de begintijd van de timingvermelding voorstelt.

  • Als deze niet is gedefinieerd, wordt de huidige tijd gebruikt als begintijd.

• end:

  • Als deze is gedefinieerd als tekenreeks: de naam van een eerder opgenomen tijdstempel.

  • Als deze is gedefinieerd als getal: een tijdstempel in milliseconden ten opzichte van Performance.timeOrigin (bijvoorbeeld genomen met performance.now()) dat de eindtijd van de timingvermelding voorstelt.

  • Als deze niet is gedefinieerd, wordt de huidige tijd gebruikt als eindtijd.

• trackName:

  De naam van de aangepaste track.

• trackGroup:

  De naam van de trackgroep.

• color:

  De kleur van de vermelding.

Uw gegevens injecteren met de API voor gebruikerstiming

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

• Gebruik performance.mark om een instantgebeurtenis of tijdstempel in de tijdlijn op te nemen. U kunt het begin of einde van een specifieke bewerking of een interessant punt zonder duur markeren. Als u een devtools-object opneemt in de detail-property, toont het deelvenster Prestaties een aangepaste markering in de track Timings.

• Gebruik performance.measure om de duur van een taak of proces te meten. Als u een devtools-object opneemt in de detail-property, toont het deelvenster Prestaties aangepaste metingsvermeldingen in de tijdlijn in een aangepaste track. Als u performance.mark gebruikt als referentiepunt 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 extensiefuncties:

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
}

Uw gegevens bekijken in de tijdlijn

Als u uw aangepaste gegevens in de tijdlijn wilt zien, zorgt u in het Prestaties deelvenster dat de instelling aanstaat: instellingen Opname-instellingen > check_box Aangepaste tracks tonen.

Probeer het op deze demopagina. Start een prestatieopname, klik op Nieuwe Corgi toevoegen op de demopagina en stop de opname. U ziet een aangepaste track in de trace met gebeurtenissen met aangepaste tooltips, details op het tabblad Overzicht en aangepaste overzichten van trackgroepen in het traceoverzicht.

Codevoorbeelden

Hier zijn een paar voorbeelden van hoe u de API gebruikt om uw eigen gegevens toe te voegen aan het deelvenster Prestaties met elk beschikbaar mechanisme.

Voorbeelden van de 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");

Dit leidt tot de volgende aangepaste trackvermelding in de prestatie-tijdlijn:

Voorbeelden van de API voor gebruikerstiming:

In de volgende gedeelten vindt u voorbeelden van code die aantonen hoe u het volgende toevoegt aan de prestatie-tijdlijn:

• Aangepaste tracks en vermeldingen in de tijdlijn
• Markeringen in de track Timings

Aangepaste tracks en vermeldingen

Maak aangepaste tracks en vul ze in 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
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"
    }
  }
});

Dit leidt tot de volgende aangepaste trackvermelding in de prestatie-tijdlijn, samen met de tooltiptekst en property's:

Markeringen

Markeer specifieke interessante punten in de tijdlijn visueel met aangepaste markeringen die alle tracks omvatten. 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 leidt tot de volgende markering in de track Timings, samen met de tooltiptekst en property's: