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, qui vous permet d'ajouter vos propres données personnalisées à la chronologie des performances.

Cette API s'appuie sur l'API User Timings existante et vous permet d'injecter vos mesures et vos événements directement dans la chronologie des performances en tant que canal personnalisé ou dans le canal 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.

Principales fonctionnalités

• Canaux personnalisés : créez des canaux dédiés pour visualiser vos propres données temporelles.
• Entrées: insérez des entrées représentant des événements ou des mesures dans les pistes.
• Info-bulles et détails : fournissez un contexte riche pour les entrées avec des info-bulles personnalisables et des vues détaillées.
• Repères : mettez en évidence des moments spécifiques de la timeline à l'aide de repères visuels.

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

• 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 de tout point d'intérêt sans 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 les entrées de mesure personnalisées dans la timeline d'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 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 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-la sur cette page de démonstration. Activez Données d'extension, lancez un enregistrement des performances, cliquez sur Ajouter un nouveau Corgi sur la page de démonstration, puis arrêtez l'enregistrement. Vous verrez un suivi personnalisé dans la trace qui contient des événements avec des info-bulles personnalisées et des détails dans l'onglet Résumé.

Exemples de code

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

• Pistes personnalisées et entrées de la timeline
• Repères pour la piste des temps

Pistes et entrées personnalisées

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 apparaît alors dans le canal Durées, avec le texte et les propriétés de son info-bulle: