Pas uw prestatiegegevens aan met de uitbreidbaarheids-API

Andrés Olivares

Sofia Emelianova

Overzicht

Wilt u dieper inzicht in de prestaties van uw applicatie, naast de ingebouwde statistieken van de browser? Met het Prestatiepaneel kunt u nu uw eigen prestatiegegevens rechtstreeks in de tijdlijn plaatsen. Of u nu een raamwerkauteur bent die interne processen moet visualiseren, een bibliotheekontwikkelaar bent die de impact van uw code bijhoudt, of een complexe applicatie bouwt met aangepaste instrumenten, de API voor prestatie-uitbreidbaarheid biedt de tools om een ​​werkelijk uitgebreid inzicht te krijgen in wat er onder de motorkap gebeurt.

Door uw aangepaste metingen en gebeurtenissen te injecteren, kunt u op maat gemaakte visualisaties creëren binnen het vertrouwde Prestatiepaneel . Stel je voor dat je de levenscyclusgebeurtenissen van de componenten van je framework ziet naast standaard browserprestatiestatistieken, of dat je de uitvoeringsstroom van je aangepaste rendering-engine volgt, in perfecte synchronisatie met de rendering-pipeline van de browser.

Deze API biedt twee benaderingen om dit te bereiken:

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

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

Belangrijkste voordelen

Beide API's bieden:

• Aangepaste tracks: voeg speciale tracks en trackgroepen toe om de unieke prestatieaspecten van uw code weer te geven.
• Inzendingen: Vul deze tracks in met vermeldingen die belangrijke gebeurtenissen of de duur van een specifieke bewerking duidelijk markeren.
• Kleuraanpassing: gebruik kleurcodering om in één oogopslag visueel onderscheid te maken tussen verschillende soorten gebeurtenissen of metingen.

De juiste API voor uw behoeften kiezen:

• console.timeStamp -API:

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

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

  • Gebruik dit wanneer u bij elke invoer extra gegevens moet opslaan en wanneer u de User Timings API al gebruikt.
  • U moet rijke gegevens (tooltips, gedetailleerde eigenschappen) koppelen aan uw prestatiegegevens.
  • 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 prestatietijdlijn van de browser voor bredere analyses of andere tools.
  • Je bent al bekend met of gebruikt de User Timings API.

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, vooral wanneer DevTools geen trace registreert.

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

• label :

  Het label voor de timinginvoer.

• start (optioneel):

  • Indien gedefinieerd als string: de naam van een eerder opgenomen tijdstempel (met behulp van console.timeStamp(timeStampName) ).

  • Indien gedefinieerd als getal: een tijdstempel in milliseconden ten opzichte van Performance.timeOrigin (bijvoorbeeld genomen met performance.now() ) die de starttijd van de timinginvoer vertegenwoordigt.

  • Indien niet gedefinieerd, wordt de huidige tijd gebruikt als starttijd.

• end :

  • Indien gedefinieerd als tekenreeks: de naam van een eerder opgenomen tijdstempel.

  • Indien gedefinieerd als getal: een tijdstempel in milliseconden ten opzichte van Performance.timeOrigin (bijvoorbeeld genomen met performance.now() ) die de eindtijd van de timinginvoer vertegenwoordigt.

  • Indien niet 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 invoer.

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
}

Bekijk uw gegevens in de tijdlijn

Als u uw aangepaste gegevens in de tijdlijn wilt zien, zorgt u er in het paneel Prestaties voor dat de instelling is ingeschakeld: settings Capture settings > check_box Show custom tracks .

Probeer het op deze demopagina . Start een opname van een optreden, klik op Nieuwe Corgi toevoegen op de demopagina en stop vervolgens de opname. U ziet een aangepaste track in de tracering 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.

console.timeStamp API-voorbeelden:

// 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 resulteert in de volgende aangepaste trackinvoer in de prestatietijdlijn:

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 tracks en vermeldingen op de tijdlijn
• Markeringen voor het timingspoor

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
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 resulteert in de volgende aangepaste trackinvoer in de prestatietijdlijn, samen met de bijbehorende tooltiptekst en eigenschappen:

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: