Personnalisez vos données de performances avec l'API d'extensibilité

Andrés Olivares

Sofia Emelianova

Présentation

Le panneau Performances est compatible avec l'API d'extensibilité des performances, ce qui permet d'ajouter des données personnalisées à la chronologie des performances. Vous pouvez ainsi injecter vos mesures et vos événements directement dans la chronologie des performances en tant que piste personnalisée ou dans la piste Timings. Cela peut être utile aux développeurs de frameworks, de bibliothèques et d'applications complexes avec une instrumentation personnalisée pour mieux comprendre les performances.

Cette API propose deux mécanismes distincts:

1. L'API User Timings (à l'aide de performance.mark et performance.measure)

Cette API s'appuie sur l'API User Timings existante. Il ajoute également des entrées au calendrier des performances interne du navigateur, ce qui permet d'effectuer des analyses plus approfondies et d'intégrer d'autres outils de performances.

2. API console.timeStamp (étendue pour DevTools)

Cette API fournit une méthode hautes performances pour instrumenter des applications et afficher des données de chronométrage exclusivement dans le panneau Performances de DevTools. Il est conçu pour réduire au maximum les coûts d'exécution, ce qui le rend adapté à l'instrumentation des chemins d'accès fréquents et des builds de production. Il n'ajoute pas d'entrées à la chronologie des performances internes du navigateur.

Principales fonctionnalités

Les deux API proposent:

• Pistes personnalisées:ajoutez des entrées à des pistes et des groupes de pistes personnalisées.
• Enregistrements: renseignez les pistes avec des enregistrements représentant des événements ou des mesures.
• Personnalisation des couleurs:attribuez des codes couleur aux entrées pour les différencier visuellement.

Différences clés et cas d'utilisation de chaque API:

• API User Timings (performance.mark, performance.measure)
  • Ajoute des entrées au panneau Performances et à la chronologie des performances internes du navigateur.
  • Permet d'utiliser des données riches, y compris des info-bulles et des propriétés détaillées.
  • Vous pouvez ajouter des repères: mettez en surbrillance des moments spécifiques de la chronologie à l'aide de repères visuels.
  • Convient pour une analyse détaillée des performances et lorsque l'intégration à d'autres outils de performances est requise.
  • À utiliser lorsque vous devez stocker des données supplémentaires avec chaque entrée et lorsque vous utilisez déjà l'API User Timings.
• API console.timeStamp:
  • Ajoute des entrées uniquement au panneau Performances.
  • Offre des performances nettement supérieures, en particulier dans les environnements de production.
  • Idéal pour instrumenter les chemins d'accès fréquents et le code critique pour les performances.
  • Vous ne pouvez pas ajouter de données supplémentaires telles que des info-bulles ou des propriétés.
  • À utiliser lorsque les coûts liés aux performances sont une préoccupation majeure et que vous devez instrumenter rapidement le code.

Injecter vos données avec l'API User Timings

Pour injecter des données personnalisées, incluez un objet devtools dans la propriété detail des méthodes performance.mark et performance.measure. La structure de cet objet devtools détermine la façon dont vos données s'affichent dans le panneau Performances.

• Utilisez performance.mark pour enregistrer un événement instantané ou un code temporel dans la timeline. Vous pouvez marquer le début ou la fin d'une opération spécifique ou d'un point d'intérêt qui n'a pas de durée. Lorsque vous incluez un objet devtools dans la propriété detail, le panneau Performances affiche un repère personnalisé dans la piste Timings.

• Utilisez performance.measure pour mesurer la durée d'une tâche ou d'un processus. Lorsque vous incluez un objet devtools dans la propriété detail, le panneau Performances affiche des entrées de mesure personnalisées dans la chronologie d'un canal personnalisé. Si vous utilisez performance.mark comme point de référence pour créer un performance.measure, vous n'avez pas besoin d'inclure l'objet devtools dans les appels performance.mark.

Objet devtools

Ces types définissent la structure de l'objet devtools pour différentes fonctionnalités d'extension:

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
}

Injecter vos données avec console.timeStamp

L'API console.timeStamp est étendue pour permettre la création d'entrées de chronométrage personnalisées dans le panneau Performances avec un coût minimal.

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

• label: libellé de l'entrée de temporisation.
• start: nom d'un code temporel précédemment enregistré (à l'aide de console.timeStamp(timeStampName)). Si non défini, l'heure actuelle est utilisée.
• end: nom d'un code temporel enregistré précédemment. Si cette valeur n'est pas définie, l'heure actuelle est utilisée.
• trackName: nom du canal personnalisé.
• trackGroup: nom du groupe de pistes.
• color: couleur de l'entrée.

Afficher vos données dans Vos trajets

Pour afficher vos données personnalisées dans la chronologie, dans le panneau Performances, activez settings Capture settings > check_box Extension data (Paramètres > Paramètres de capture > Case à cocher : Données d'extension).

Essayez-le sur cette page de démonstration. Activez Données d'extension, démarrez un enregistrement des performances, cliquez sur Ajouter un Corgi sur la page de démonstration, puis arrêtez l'enregistrement. Dans la trace, vous verrez un canal personnalisé contenant des événements avec des info-bulles et des détails personnalisés dans l'onglet Récapitulatif.

Exemples de code

Voici quelques exemples d'utilisation de l'API pour ajouter vos propres données au panneau Performances à l'aide de chaque mécanisme disponible.

Exemples d'utilisation de l'API User Timings:

Dans les sections suivantes, vous trouverez des exemples de code qui montrent comment ajouter les éléments suivants à la chronologie des performances:

• Pistes et entrées personnalisées dans la timeline
• Repères sur la piste "Temps de chargement"

Canaux et entrées personnalisés

Créez des canaux personnalisés et remplissez-les d'entrées pour visualiser vos données de performances dans un canal personnalisé. Exemple :

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

L'entrée de trace personnalisée suivante s'affiche dans la chronologie des performances, avec son texte d'info-bulle et ses propriétés:

Repères

Mettez en avant visuellement des points d'intérêt spécifiques dans la chronologie à l'aide de repères personnalisés qui s'étendent sur toutes les pistes. Exemple :

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

Le repère suivant s'affiche dans le canal Timings, avec son texte d'info-bulle et ses propriétés:

Exemples d'API console.timeStamp:

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

Vous obtenez alors l'entrée de trace personnalisée suivante dans la chronologie des performances: