Personnaliser le profil de performances avec les API d’extensibilité

Contenu détaillé :

• Vue d’ensemble
• Avantages clés
  • Choisir l’API appropriée
• Injecter vos données avec console.timeStamp()
• Injecter vos données avec l’API Minutage utilisateur
  • devtools objet
• Afficher vos données personnalisées dans le profil de performances
• Exemples de code
  • console.timeStamp() Exemples d’API
  • Exemples d’API Minutage utilisateur
    • Ajouter des pistes et des entrées personnalisées à la chronologie (performance.measure())
    • Ajouter des marqueurs à la piste Minutage (performance.mark())
• Voir aussi

Vue d’ensemble

L’outil Performance peut afficher vos propres données de performances, en plus des métriques intégrées du navigateur. L’affichage de vos propres données de performances personnalisées dans l’outil Performance peut être utile dans les cas suivants :

• Création d’une infrastructure et vous devez visualiser les processus internes.
• Développement d’une bibliothèque et vous souhaitez suivre l’impact de votre code.
• Création d’une application web complexe avec beaucoup de traitement côté client.

Les API d’extensibilité des performances permettent de comprendre ce qui se passe dans votre code.

En injectant des mesures et des événements personnalisés, vous pouvez créer des visualisations personnalisées dans l’outil Performance .

Les API d’extensibilité des performances sont deux approches pour y parvenir :

1. L’API console.timeStamp() (étendue pour DevTools)

   Cette API fournit une méthode hautes performances pour l’instrumentation des applications et l’exposition des données de minutage exclusivement à l’outil Performance dans DevTools. Il est conçu pour une surcharge d’exécution minimale, ce qui le rend adapté à l’instrumentation des chemins d’accès chauds et des builds de production. Il n’ajoute pas d’entrées aux chronologie de performances internes du navigateur.

2. API Minutage utilisateur (à l’aide de performance.mark() et performance.measure())

   Cette API tire parti de l’API Minutage utilisateur existante. Il ajoute également des entrées aux chronologie de performances internes du navigateur, ce qui permet d’approfondir l’analyse et l’intégration avec d’autres outils de performances. Consultez API de performances sur MDN.

La capture d’écran ci-dessus a les zones suivantes ajoutées, pour mettre en surbrillance les résultats :

• Zone rouge dans la piste Minutage : performance.mark(). Les marqueurs personnalisés sont Démarrer le filtrage, Filtrage terminé et Photo sélectionnée. Les traits en pointillés verticaux s’étendent sur toutes les pistes.

• Zone bleue dans la piste de création de photos personnalisée : performance.measure()

• Zone verte dans la piste de suivi de l’horodatage de la console personnalisée : console.timeStamp()

Avantages clés

Les deux API offrent :

• Pistes personnalisées : Ajoutez des pistes dédiées et des groupes de suivi, dans un profil de performances, pour représenter les aspects de performances uniques de votre code.

• Entrées: Renseignez ces pistes avec des entrées qui marquent clairement les événements importants ou la durée d’une opération spécifique.

• Personnalisation de la couleur : Utilisez le codage en couleur pour distinguer visuellement les différents types d’événements ou de mesures en un coup d’œil.

Choisir l’API appropriée

L’API console.timeStamp() minutage utilisateur et sert différents besoins.

Utilisez l’API console.timeStamp() dans les cas suivants :

• L’impact sur les performances de l’instrumentation est un problème majeur, 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 avez uniquement besoin que les données soient visualisées dans l’outil Performance .

Utilisez l’API Minutage utilisateur (performance.mark() ou performance.measure()) dans les cas suivants :

• Vous devez stocker des données supplémentaires avec chaque entrée et lorsque vous utilisez déjà l’API Minutage utilisateur.

• Vous devez associer des données enrichies (info-bulles, propriétés détaillées) à vos entrées de performances.

• Vous souhaitez ajouter des marqueurs visuels pour mettre en surbrillance des moments spécifiques.

• Vous devez que les données soient disponibles non seulement dans DevTools, mais également dans les chronologie de performances internes du navigateur pour une analyse plus large ou d’autres outils.

• Vous connaissez déjà ou utilisez l’API Minutage utilisateur.

La démonstration de la Galerie de photos illustre toutes ces API.

Injecter vos données avec console.timeStamp()

L’API console.timeStamp() est étendue pour permettre la création d’entrées de minutage personnalisées dans l’outil Performance avec une surcharge minimale, en particulier lorsque DevTools n’enregistre pas de trace.

Syntaxe :

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

• label:

  Étiquette de l’entrée de minutage.

• start (facultatif) :

  • S’il est défini comme une chaîne : nom d’un horodatage précédemment enregistré (à l’aide de console.timeStamp(timeStampName)).

  • S’il est défini comme un 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 minutage.

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

• end:

  • S’il est défini comme une chaîne : nom d’un horodatage précédemment enregistré.

  • S’il est défini comme un 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 minutage.

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

Voir aussi :

• Spécification de l’extension console.timeStamp : version à 6 paramètres de la méthode.
  • console : méthode statique timeStamp() : version à 1 paramètre de la méthode.

Injecter vos données avec l’API Minutage utilisateur

Pour injecter des données personnalisées, incluez un devtools objet dans la propriété detail de la performance.mark() méthode ou dans la propriété detail de la performance.measure() méthode. La structure de cet devtools objet détermine la façon dont vos données sont affichées dans l’outil Performance .

• Utilisez performance.mark() pour enregistrer un événement instantané ou un horodatage dans le 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 devtools objet dans la detail propriété, l’outil Performance affiche un marqueur personnalisé dans la piste Minutage .

• Utilisez performance.measure() pour mesurer la durée d’une tâche ou d’un processus. Lorsque vous incluez un devtools objet dans la detail propriété, l’outil Performance affiche des entrées de mesure personnalisées dans le chronologie dans une piste personnalisée. 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 dans performance.mark() les devtools appels.

devtools objet

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 personnalisées dans le profil de performances

Pour afficher vos données personnalisées dans un profil de performances enregistré, dans l’outil Performance , commencez par utiliser l’une des API d’extensibilité des performances, puis enregistrez un profil.

Pour enregistrer un profil et afficher les données de performances personnalisées de la page de démonstration de la Galerie de photos :

1. Ouvrez la page web de démonstration de la Galerie de photos dans une nouvelle fenêtre ou un nouvel onglet.

   Ou, pour pouvoir modifier l’exemple de code :

   1. Clonez le dépôt « MicrosoftEdge / Demos », par exemple Cloner le dépôt de démonstrations Edge sur votre lecteur.
   2. Démarrez un serveur localhost dans le répertoire cloné /demos/ , selon Démarrer le serveur localhost, dans Exemple de code pour DevTools.
   3. Dans le navigateur, accédez à ou équivalent http://localhost:8080/photo-gallery/ , dans une nouvelle fenêtre ou un nouvel onglet.

2. Cliquez avec le bouton droit sur la page web, puis sélectionnez Inspecter.

   DevTools s’ouvre.

3. Dans DevTools, sélectionnez l’outil Performance ().

4. Dans l’outil Performances , cliquez sur le bouton Paramètres de capture (), puis vérifiez que la case Afficher les pistes personnalisées est cochée :

   

5. Dans la liste déroulante Limitation du processeur , sélectionnez Ralentissement 4x - recommandé.

   Un indicateur d’avertissement de limitation est ajouté à l’onglet Performances .

6. Actualisez la page pour effacer toutes les sélections.

7. Cliquez sur le bouton Enregistrer ().

8. En haut de la page de démonstration, dans le menu déroulant Appareil photo () à gauche, passez de Tous à Apple iPhone 12.

9. Remplacez le filtre Caméra par Tout.

10. Cliquez sur la première photo.

    La photo se développe.

11. Dans DevTools, cliquez sur le bouton Arrêter .

    Le profil s’affiche.

12. Cliquez sur Personnaliser et contrôler DevTools (), puis en regard de Emplacement d’ancrage, sélectionnez Undock in separate window ().

    DevTools étant détaché dans sa propre fenêtre, il est plus facile d’afficher davantage de données.

13. Faites défiler vers le bas jusqu’au groupe Minutages de performances personnalisés — Suivi personnalisé , puis développez-le.

14. Développez les pistes personnalisées :

    • Création de photos
    • Suivi de l’horodatage de la console

15. Utilisez la souris et les touches de direction pour déplacer et zoomer le profil, afin d’afficher les mesures de performances personnalisées :

    

16. Pointez sur un marqueur dans une piste personnalisée, comme un marqueur De chargement dans la piste de chargement .

    Une info-bulle personnalisée s’affiche, y compris la durée et la légende.

17. Sélectionnez un marqueur dans une piste personnalisée.

    Dans l’onglet Résumé en bas de l’outil Performances , les détails du marqueur sont affichés.

Le code qui définit ces mesures de performances personnalisées est indiqué dans Ajouter des pistes et des entrées personnalisées à la chronologie (performance.measure()), ci-dessous.

Exemples de code

Voici quelques exemples d’utilisation de l’API pour ajouter vos propres données à l’outil Performance à l’aide de chaque mécanisme disponible.

console.timeStamp() Exemples d’API

Par exemple, dans la galerie de photos/gallery.js, la loadPhoto() fonction définit un startTime et endTime en appelant performance.now(), puis appelle console.timeStamp() pour afficher le temps nécessaire au chargement d’une photo après un clic sur cette photo :

// Load a photo and return a promise that resolves when the photo is loaded.
function loadPhoto(fileName) {
  // Record the start time of the photo loading for performance tracking.
  const startTime = performance.now();

  return new Promise(resolve => {
    // Load the image by creating a new image element.
    const imageEl = document.createElement("img");
    imageEl.src = fileName;

    // Listen for the load event to resolve the promise when the image is loaded.
    imageEl.addEventListener('load', () => {
      // Record the end time of the photo loading.
      const endTime = performance.now();

      // Display the photo loading duration in the Performance tool, by using console.timeStamp.
      console.timeStamp("Loading photo",              // label
                        startTime,                    // start
                        endTime,                      // end
                        "Console timestamp track",    // trackName
                        "Custom performance timings", // trackGroup
                        "primary-dark");              // color

      resolve(imageEl);
    }, { once: true });
  });
}

Pour afficher le profil résultant :

1. Effectuez les étapes décrites dans Afficher vos données personnalisées dans le profil de performances ci-dessus.

2. Faites défiler vers le bas jusqu’au groupe Minutages de performances personnalisés — Suivi personnalisé , puis développez-le.

3. Développez la piste d’horodatage de la console.

4. Utilisez la souris et les touches de direction pour déplacer et zoomer le profil, afin d’afficher les mesures de performances personnalisées :

   

   L’événement loading photo a été créé à l’aide de console.timeStamp(). Cet événement a une durée, car il est créé avec une heure de début et une heure de fin. Cet événement correspond au temps nécessaire pour charger la version plein écran de la photo sur laquelle vous avez cliqué.

Voir aussi :

• Injecter vos données avec console.timeStamp() (ci-dessus) - syntaxe.
• performance.now()

Exemples d’API Minutage utilisateur

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

• Ajouter des pistes et des entrées personnalisées à la chronologie (performance.measure())
• Ajouter des marqueurs à la piste Minutage (performance.mark())

Ajouter des pistes et des entrées personnalisées à la chronologie (performance.measure())

Créez des pistes personnalisées et renseignez-les avec des entrées pour visualiser vos données de performances dans une piste personnalisée.

Par exemple, dans la galerie de photos/gallery.js, la populateGallery() fonction définit un startTime et endTime en appelant performance.now(), puis appelle performance.measure() pour afficher le temps nécessaire à la création d’une photo dans la galerie :

// Populate the gallery with the given images.
function populateGallery(images) {
  // Empty the existing gallery elements.
  galleryEl.innerHTML = '';

  // Iterate over the images.
  images.forEach(({ file, user, description, w, h, meta }) => {
    // Record the start time of this image creation for performance tracking.
    const startTime = performance.now();

    // Create the necessary DOM elements, and append them to the gallery.
    const liEl = createImageDOM(file, user, description, meta, w, h);
    galleryEl.appendChild(liEl);

    // Record the end time of this image creation.
    const endTime = performance.now();

    // Display the image creation duration in the Performance tool
    // by using the performance.measure API, with the devtools
    // object.
    performance.measure(`Image ${file} created`, {
      start: startTime,
      end: endTime,
      detail: {
        devtools: {
          dataType: "track-entry",
          color: "primary",
          trackGroup: "Custom performance timings",
          track: "Photo creation",
          properties: [
            ['File', file],
            ['Width', w],
            ['Height', h],
            ['User', user],
          ],
          tooltipText: `Image ${file} created`
        }
      },
    });
  });
}

Pour afficher le profil résultant :

1. Effectuez les étapes décrites dans Afficher vos données personnalisées dans le profil de performances ci-dessus.

2. Faites défiler vers le bas jusqu’au groupe Minutages de performances personnalisés — Suivi personnalisé , puis développez-le.

3. Développez la piste Création de photos.

4. Utilisez la souris et les touches de direction pour déplacer et zoomer le profil, afin d’afficher les mesures de performances personnalisées.

   Il en résulte l’entrée de piste personnalisée suivante dans le chronologie de performances, ainsi que son texte d’info-bulle et ses propriétés :

   

   Les événements créés par performance.measure() ont une courte durée. Vous devez donc effectuer un zoom avant pour les afficher dans le profil. Chacun de ces événements enregistre la création d’une image, qui se produit lorsque vous modifiez la valeur du filtre (liste déroulante) et lorsque l’interface utilisateur de la galerie entière est actualisée.

   Les événements de création de photos s’affichent entre les Start filtering marques de performance et Done filtering qui en résultent performance.mark() (abordées dans la section suivante) :

   

Voir aussi :

• performance.measure()
• performance.now()

Ajouter des marqueurs à la piste Minutage (performance.mark())

Mettez en surbrillance visuellement des points d’intérêt spécifiques dans le chronologie avec des marqueurs personnalisés qui s’étendent sur toutes les pistes.

Par exemple, dans la galerie de photos/gallery.js, un écouteur d’événements gère les événements dans les listes déroulantes input de filtre de la page de démonstration. L’écouteur d’événements appelle performance.mark() deux fois : avant l’application du nouveau filtre et après l’application du nouveau filtre :

// Handle input events on the filter selects.
addEventListener('input', e => {
  // Check if the input event is from a filter select.
  // If not, return early.
  const filter = e.target.closest('.filter select');
  if (!filter) {
    return;
  }

  // Add a mark in the Performance tool's recorded profile to
  // indicate that a filter will be applied.
  performance.mark("Start filtering", {
    detail: {
      devtools: {
        dataType: "marker",
        color: "secondary",
        properties: [
          ['Filter Value', filter.value]
        ],
        tooltipText: "Start filtering"
      }
    }
  });

  // Reset the other filters.
  filterEl.querySelectorAll('.filter select').forEach(select => {
    if (select !== filter) {
      select.selectedIndex = 0;
    }
  });

  // Apply the filter based on the selected value.
  filterBy(filter);

  // Add a mark in the Performance tool's recorded profile to
  // indicate that a filter was applied.
  performance.mark("Done filtering", {
    detail: {
      devtools: {
        dataType: "marker",
        color: "tertiary",
        properties: [
          ['Filter Value', filter.value]
        ],
        tooltipText: "Done filtering"
      }
    }
  });
});

// Handle click events on photos.
addEventListener('click', e => {
  const clickedPhoto = e.target.tagName === 'IMG' && e.target.closest('.photo');
  if (!clickedPhoto) {
    return;
  }

  // Add a mark in the Performance tool's recorded profile to
  // indicate that a photo was clicked.
  performance.mark("Photo selected", {
    detail: {
      devtools: {
        dataType: "marker",
        color: "secondary-dark",
        properties: [
          ['photo', clickedPhoto.src]
        ],
        tooltipText: "Photo selected"
      }
    }
  });

  selectPhoto(clickedPhoto);
});

Pour afficher le profil résultant :

1. Effectuez les étapes décrites dans Afficher vos données personnalisées dans le profil de performances ci-dessus.

2. Utilisez la souris et les touches de direction pour déplacer et zoomer le profil, afin d’afficher les mesures de performances personnalisées.

   La piste Minutage affiche les marqueurs personnalisés Démarrer le filtrage, Filtrage terminé et Photo sélectionnée :

   

   Les événements (marqueurs) créés par performance.mark() n’ont pas de durée ; ils marquent simplement des événements intéressants dans un profil : le début et la fin d’un changement de filtre (à l’aide des menus déroulants de la page de démonstration) et le moment où une photo a été sélectionnée (le marqueur Photo sélectionné ).

Voir aussi :

• Performances : méthode mark()

Voir aussi

MDN :

• Spécification de l’extension console.timeStamp : version à 6 paramètres de la méthode.
  • console : méthode statique timeStamp() : version à 1 paramètre de la méthode.
• API de performances
  • Minutage de l’utilisateur dans LES > API web API de performances.
• Performances : méthode mark()
• Performance : méthode measure()
• Performance : méthode now()
• Performance : propriété timeOrigin

Démos:

• Galerie de photos : application web en cours d’exécution.
  • photo-gallery/gallery.js : code source.

Remarque

Les parties de cette page sont des modifications basées sur le travail créé et partagé par Google et utilisées conformément aux termes décrits dans la licence internationale Creative Commons Attribution 4.0. La page d’origine est trouvée ici et est créée par Andrés Oliviares et Sofia Emelianova.

Cette œuvre est concédée sous licence creative commons attribution 4.0 international.