Descripción general
El panel Rendimiento admite la API de extensibilidad de rendimiento, lo que permite agregar datos personalizados al cronograma de rendimiento. Esto 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.
Esta API ofrece dos mecanismos distintos:
1. La API de User Timings (con performance.mark
y performance.measure
)
Esta API aprovecha la API de User Timings existente. También agrega entradas al cronograma de rendimiento interno del navegador, lo que permite un análisis más detallado y la integración con otras herramientas de rendimiento.
2. La API de console.timeStamp
(extendida para DevTools)
Esta API proporciona un método de alto rendimiento para instrumentar aplicaciones y mostrar datos de tiempo exclusivamente en el panel Rendimiento de DevTools. Está diseñado para una sobrecarga mínima del entorno de ejecución, lo que lo hace adecuado para instrumentar instrucciones de código de acceso directo y compilaciones de producción. No agrega entradas al cronograma de rendimiento interno del navegador.
Características clave
Ambas APIs ofrecen lo siguiente:
- Pistas personalizadas: Agrega entradas a pistas y grupos de pistas personalizados.
- Entradas: Completa segmentos con entradas que representen eventos o mediciones.
- Personalización de colores: Entradas con códigos de color para la diferenciación visual.
Diferencias clave y cuándo usar cada API:
- API de User Timings (
performance.mark
,performance.measure
):- Agrega entradas al panel Rendimiento y a la línea de tiempo de rendimiento interna del navegador.
- Permite datos enriquecidos, incluidas ventanas de información y propiedades detalladas.
- Permite agregar marcadores: Destaca momentos específicos en el cronograma con marcadores visuales.
- Adecuada para el análisis de rendimiento detallado y cuando se requiere la integración con otras herramientas de rendimiento.
- Úsala cuando necesites almacenar datos adicionales con cada entrada y cuando ya uses la API de User Timings.
- API de
console.timeStamp
:- Agrega entradas solo al panel Rendimiento.
- Ofrece un rendimiento significativamente mayor, especialmente en entornos de producción.
- Ideal para instrumentar instrucciones de código de alto rendimiento y de rendimiento crítico.
- No se pueden agregar datos adicionales, como propiedades o cuadros de información.
- Úsala cuando la sobrecarga de rendimiento sea una preocupación principal y necesites instrumentar el código rápidamente.
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 la línea de tiempo. 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 objetodevtools
dentro de la propiedaddetail
, 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 objetodevtools
dentro de la propiedaddetail
, el panel Rendimiento muestra entradas de medición personalizadas en la línea de tiempo en un segmento personalizado. Si usasperformance.mark
como punto de referencia para crear unperformance.measure
, no necesitas incluir el objetodevtools
en las llamadas aperformance.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 insertar tus datos con console.timeStamp
La API de console.timeStamp se extiende para permitir la creación de entradas de tiempo personalizadas en el panel Rendimiento con una sobrecarga mínima.
console.timeStamp(label: string, start?: string, end?: string, trackName?: string, trackGroup?: string, color?: DevToolsColor);
label
: Es la etiqueta de la entrada de tiempo.start
: Es el nombre de una marca de tiempo registrada anteriormente (conconsole.timeStamp(timeStampName)
). Si no se define, se usa la hora actual.end
: Es el nombre de una marca de tiempo registrada anteriormente. Si no se define, se usa la hora actual.trackName
: Es el nombre del segmento personalizado.trackGroup
: Es el nombre del grupo de pistas.color
: Es el color de la entrada.
Cómo ver tus datos en la Ruta
Para ver tus datos personalizados en el cronograma, en el panel Rendimiento, activa
Configuración de captura > 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
Estos son algunos ejemplos de cómo usar la API para agregar tus propios datos al panel Rendimiento con cada mecanismo disponible.
Ejemplos de la API de User Timings:
En las siguientes secciones, consulta los ejemplos de código que muestran cómo agregar lo siguiente al cronograma de rendimiento:
Segmentos y entradas personalizados
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 de rendimiento, junto con su texto y propiedades de la herramienta de ayuda:
Marcadores
Destaca visualmente lugares 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:
Ejemplos de la API de 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");
Esto genera la siguiente entrada de segmento personalizado en el cronograma de rendimiento: