Personaliza tus datos de rendimiento con la API de Extensibility

Andrés Olivares

Sofia Emelianova

Descripción general

El panel Rendimiento admite la API de extensibilidad de rendimiento que te permite agregar tus propios datos personalizados a la línea de tiempo de rendimiento.

Esta API aprovecha la API de User Timings existente y te permite insertar tus mediciones y eventos directamente en el cronograma de rendimiento como un segmento personalizado o en el segmento Timings. Esto puede ser útil para los desarrolladores de frameworks, bibliotecas y aplicaciones complejas con instrumentación personalizada para obtener una comprensión más integral del rendimiento.

Características clave

• Pistas personalizadas: Crea segmentos exclusivos para visualizar tus propios datos basados en el tiempo.
• Entradas: Completa segmentos con entradas que representen eventos o mediciones.
• Detalles y cuadros de información: Proporciona contexto enriquecido para las entradas con cuadros de información personalizables y vistas detalladas.
• Marcadores: Destaca momentos específicos en la línea de tiempo con marcadores visuales.

Cómo insertar tus datos con la API de User Timing

Para insertar datos personalizados, incluye un objeto devtools dentro de la propiedad detail de los métodos performance.mark y performance.measure. La estructura de este objeto devtools determina cómo se muestran tus datos en el panel Rendimiento.

• Usa performance.mark para registrar un evento instantáneo o una marca de tiempo en el cronograma. Puedes marcar el inicio o el final de una operación específica o cualquier punto de interés que no tenga una duración. Cuando incluyes un objeto devtools dentro de la propiedad detail, el panel Rendimiento muestra un marcador personalizado en la pista Tiempo.

• Usa performance.measure para medir la duración de una tarea o un proceso. Cuando incluyes un objeto devtools dentro de la propiedad detail, el panel Rendimiento muestra entradas de medición personalizadas en la línea de tiempo en un segmento personalizado. Si usas performance.mark como punto de referencia para crear un performance.measure, no necesitas incluir el objeto devtools en las llamadas a performance.mark.

Objeto devtools

Estos tipos definen la estructura del objeto devtools para diferentes funciones de extensión:

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
}

Cómo ver tus datos en la Ruta

Para ver tus datos personalizados en el cronograma, en el panel Rendimiento, activa configuración Configuración de captura > check_box Datos de extensión.

Pruébala en esta página de demostración. Activa Datos de extensión, inicia una grabación de rendimiento, haz clic en Agregar nuevo Corgi en la página de demostración y, luego, detén la grabación. Verás un segmento personalizado en el registro que contiene eventos con detalles y cuadros de herramientas personalizados en la pestaña Resumen.

Ejemplos de código

En las siguientes secciones, consulta los ejemplos de código que muestran cómo agregar lo siguiente al cronograma de rendimiento:

• Pistas y entradas personalizadas en la línea de tiempo
• Marcadores en la pista de tiempos

Pistas y entradas personalizadas

Crea segmentos personalizados y complétalos con entradas para visualizar tus datos de rendimiento en un segmento personalizado. Por ejemplo:

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

Esto genera la siguiente entrada de segmento personalizado en la línea de tiempo del rendimiento, junto con su texto y propiedades de la herramienta de ayuda:

Marcadores

Destaca visualmente puntos de interés específicos en la línea de tiempo con marcadores personalizados que abarcan todas las pistas. Por ejemplo:

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

Esto genera el siguiente marcador en la pista Timings, junto con su texto y propiedades de la herramienta de ayuda: