Personalize seus dados de desempenho com a API de extensibilidade

Andrés Olivares

Sofia Emelianova

Visão geral

O painel Performance oferece suporte à API de extensibilidade de performance, permitindo a adição de dados personalizados à linha do tempo de performance. Assim, você pode injetar suas medições e eventos diretamente na linha do tempo de performance como uma faixa personalizada ou na faixa Tempos. Isso pode ser útil para desenvolvedores de frameworks, bibliotecas e aplicativos complexos com instrumentação personalizada para entender melhor a performance.

Essa API oferece dois mecanismos distintos:

1. A API User Timings (usando performance.mark e performance.measure)

Essa API aproveita a API User Timings. Ele também adiciona entradas à linha do tempo de desempenho interna do navegador, permitindo mais análises e integração com outras ferramentas de performance.

2. A API console.timeStamp (estendida para as Ferramentas do desenvolvedor)

Essa API oferece um método de alto desempenho para instrumentar aplicativos e mostrar dados de tempo exclusivamente no painel Performance no DevTools. Ele foi projetado para ter um overhead mínimo de execução, o que o torna adequado para instrumentar caminhos de execução e builds de produção. Ele não adiciona entradas à linha do tempo de desempenho interno do navegador.

Principais recursos

Ambas as APIs oferecem:

• Faixas personalizadas:adicione entradas a faixas e grupos de faixas personalizados.
• Entradas: preencha faixas com entradas que representam eventos ou medições.
• Personalização de cores:entradas com código de cores para diferenciação visual.

Diferenças principais e quando usar cada API:

• API User Timings (performance.mark, performance.measure):
  • Adiciona entradas ao painel Performance e à linha do tempo de performance interna do navegador.
  • Permite dados ricos, incluindo dicas e propriedades detalhadas.
  • Permite adicionar marcadores: destaque momentos específicos na linha do tempo com marcadores visuais.
  • Adequado para análises detalhadas de desempenho e quando a integração com outras ferramentas de performance é necessária.
  • Use quando precisar armazenar dados extras com cada entrada e quando já estiver usando a API User Timings.
• API console.timeStamp:
  • Adiciona apenas entradas ao painel Performance.
  • Oferece desempenho significativamente maior, especialmente em ambientes de produção.
  • Ideal para instrumentar caminhos de acesso rápidos e códigos críticos para o desempenho.
  • Não é possível adicionar dados extras, como dicas de ferramentas ou propriedades.
  • Use quando a sobrecarga de desempenho for uma preocupação principal e você precisar instrumentar o código rapidamente.

Injete seus dados com a API User Timings

Para injetar dados personalizados, inclua um objeto devtools na propriedade detail dos métodos performance.mark e performance.measure. A estrutura desse objeto devtools determina como os dados são mostrados no painel Performance.

• Use performance.mark para registrar um evento instantâneo ou um carimbo de data/hora na linha do tempo. É possível marcar o início ou o fim de uma operação específica ou qualquer ponto de interesse que não tenha duração. Quando você inclui um objeto devtools na propriedade detail, o painel Performance mostra um marcador personalizado na faixa Tempos.

• Use performance.measure para medir a duração de uma tarefa ou processo. Quando você inclui um objeto devtools na propriedade detail, o painel Performance mostra entradas de medição personalizadas na linha do tempo em uma faixa personalizada. Se você estiver usando performance.mark como ponto de referência para criar um performance.measure, não será necessário incluir o objeto devtools nas chamadas de performance.mark.

Objeto devtools

Esses tipos definem a estrutura do objeto devtools para diferentes recursos de extensão:

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
}

Injete seus dados com console.timeStamp

A API console.timeStamp foi ampliada para permitir a criação de entradas de tempo personalizadas no painel Performance com um mínimo de sobrecarga.

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

• label: o rótulo da entrada de tempo.
• start: o nome de um carimbo de data/hora registrado anteriormente (usando console.timeStamp(timeStampName)). Se não for definido, o horário atual será usado.
• end: o nome de um carimbo de data/hora gravado anteriormente. Se não for definido, o horário atual será usado.
• trackName: o nome da faixa personalizada.
• trackGroup: o nome do grupo de faixas.
• color: a cor da entrada.

Conferir seus dados na linha do tempo

Para ver seus dados personalizados na linha do tempo, no painel Performance, ative settings Capture settings > check_box Extension data.

Teste nesta página de demonstração. Ative a opção Dados da extensão, inicie uma gravação de performance, clique em Adicionar novo Corgi na página de demonstração e interrompa a gravação. Uma faixa personalizada vai aparecer no rastreamento, contendo eventos com dicas de ferramentas e detalhes personalizados na guia Resumo.

Exemplos de código

Confira alguns exemplos de como usar a API para adicionar seus próprios dados ao painel Performance usando cada mecanismo disponível.

Exemplos da API User Timings:

Nas próximas seções, confira os exemplos de código que mostram como adicionar os seguintes itens à linha do tempo de performance:

• Faixas e entradas personalizadas na linha do tempo
• Marcadores na faixa "Tempo"

Faixas e entradas personalizadas

Crie faixas personalizadas e as preencha com entradas para visualizar seus dados de desempenho em uma faixa personalizada. Exemplo:

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

Isso resulta na seguinte entrada de faixa personalizada na linha do tempo de performance, com o texto e as propriedades da dica:

Marcadores

Destaque pontos de interesse específicos na linha do tempo com marcadores personalizados que abrangem todas as faixas. Exemplo:

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

Isso resulta no marcador a seguir na faixa Timings, com o texto e as propriedades da dica de ferramenta:

Exemplos de APIs 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");

Isso resulta na seguinte entrada de faixa personalizada na linha do tempo de desempenho: