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

Andrés Olivares

Sofia Emelianova

Présentation

Vous souhaitez obtenir des insights plus approfondis sur les performances de votre application au-delà des métriques intégrées du navigateur ? Le panneau Performances vous permet désormais d'intégrer vos propres données sur les performances directement dans la chronologie. Que vous soyez l'auteur d'un framework qui a besoin de visualiser des processus internes, un développeur de bibliothèque qui suit l'impact de son code ou que vous créiez une application complexe avec une instrumentation personnalisée, l'API d'extensibilité des performances fournit les outils nécessaires pour obtenir une compréhension véritablement complète de ce qui se passe en coulisses.

En injectant vos mesures et événements personnalisés, vous pouvez créer des visualisations personnalisées dans le panneau Performances que vous connaissez bien. Imaginez voir les événements du cycle de vie des composants de votre framework à côté des métriques de performances standards du navigateur, ou suivre le flux d'exécution de votre moteur de rendu personnalisé en parfaite synchronisation avec le pipeline de rendu du navigateur.

Cette API propose deux approches pour y parvenir :

1. L'API console.timeStamp (étendue pour les outils de développement)

Cette API fournit une méthode hautes performances pour instrumenter les applications et afficher les données de timing exclusivement dans le panneau Performances des outils de développement. Elle est conçue pour minimiser la surcharge d'exécution, ce qui la rend adaptée à l'instrumentation des chemins critiques et des builds de production. Elle n'ajoute pas d'entrées à la chronologie des performances internes du navigateur.

2. L'API User Timings (avec performance.mark et performance.measure)

Cette API exploite l'API User Timings existante. Elle ajoute également des entrées à la chronologie des performances internes du navigateur, ce qui permet une analyse plus approfondie et une intégration à d'autres outils de performances.

Principaux avantages

Les deux API offrent les avantages suivants :

• Pistes personnalisées : ajoutez des pistes et des groupes de pistes dédiés pour représenter les aspects uniques des performances de votre code.
• Entrées : remplissez ces pistes avec des entrées qui marquent clairement les événements importants ou la durée d'une opération spécifique.
• Personnalisation des couleurs : utilisez des codes couleur pour distinguer visuellement différents types d'événements ou de mesures en un coup d'œil.

Choisir l'API adaptée à vos besoins :

• API console.timeStamp :

  • L'impact de l'instrumentation sur les performances est une préoccupation majeure, en particulier dans les builds de production.
  • Vous avez besoin d'un moyen rapide et efficace de marquer des durées ou des événements sans avoir besoin de métadonnées supplémentaires.
  • Vous n'avez besoin que des données à visualiser dans le panneau "Performances".

• API User Timings (performance.mark, performance.measure) :

  • Utilisez-la lorsque vous devez stocker des données supplémentaires avec chaque entrée et lorsque vous utilisez déjà l'API temps utilisateur.
  • Vous devez associer des informations enrichies (info-bulles, propriétés détaillées) à vos entrées de performances.
  • Vous souhaitez ajouter des repères visuels pour mettre en évidence des moments spécifiques.
  • Vous avez besoin que les données soient disponibles non seulement dans les outils de développement, mais également dans la chronologie des performances internes du navigateur pour une analyse plus large ou d'autres outils.
  • Vous connaissez déjà l'API User Timings ou l'utilisez déjà.

Injecter vos données avec console.timeStamp

L'API console.timeStamp est étendue pour permettre la création d'entrées de timing personnalisées dans le panneau Performances avec une surcharge minimale, en particulier lorsque les outils de développement n'enregistrent pas de trace.

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

• label:

  Libellé de l'entrée de timing.

• start (facultatif) :

  • Si elle est définie en tant que chaîne : nom d'un horodatage précédemment enregistré (à l'aide de console.timeStamp(timeStampName)).

  • Si elle est définie en tant que nombre : horodatage en millisecondes par rapport à Performance.timeOrigin (par exemple, pris avec performance.now()) qui représente l'heure de début de l'entrée de timing.

  • Si elle n'est pas définie, l'heure actuelle est utilisée comme heure de début.

• end:

  • Si elle est définie en tant que chaîne : nom d'un horodatage précédemment enregistré.

  • Si elle est définie en tant que nombre : horodatage en millisecondes par rapport à Performance.timeOrigin (par exemple, pris avec performance.now()) qui représente l'heure de fin de l'entrée de timing.

  • Si elle n'est pas définie, l'heure actuelle est utilisée comme heure de fin.

• trackName:

  Nom de la piste personnalisée.

• trackGroup:

  Nom du groupe de pistes.

• color:

  Couleur de l'entrée.

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 sont affichées dans le panneau Performances.

• Utilisez performance.mark pour enregistrer un événement instantané ou un horodatage dans la chronologie. Vous pouvez marquer le début ou la fin d'une opération spécifique ou tout 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'une piste personnalisée. Si vous utilisez performance.mark comme point de référence pour créer une 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
}

Afficher vos données dans la chronologie

Pour afficher vos données personnalisées dans la chronologie, dans le panneau Performances, assurez-vous que le paramètre est activé : settings Paramètres de capture > check_box Afficher les pistes personnalisées.

Essayez-le sur cette page de démonstration. Démarrez un enregistrement des performances, cliquez sur Add new Corgi (Ajouter un nouveau Corgi) sur la page de démonstration, puis arrêtez l'enregistrement. Vous verrez une piste personnalisée dans la trace qui contient des événements avec des info-bulles personnalisées, des détails dans l'onglet Summary (Récapitulatif) et des résumés de groupes de pistes personnalisés dans le résumé de la trace.

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

Cela génère l'entrée de piste personnalisée suivante dans la chronologie des performances :

Exemples d'API User Timings :

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

• Pistes et entrées personnalisées dans la chronologie
• Repères dans la piste "Timings"

Pistes et entrées personnalisées

Créez des pistes personnalisées et remplissez-les avec des entrées pour visualiser vos données sur les performances dans une piste personnalisée. Exemple :

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

Cela génère l'entrée de piste personnalisée suivante dans la chronologie des performances, ainsi que son texte d'info-bulle et ses propriétés :

Repères

Mettez en évidence 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"
    }
  }
});

Cela génère le repère suivant dans la piste Timings, ainsi que son texte d'info-bulle et ses propriétés :