Personalize seus dados de desempenho com a API de extensibilidade

Andrés Olivares

Sofia Emelianova

Visão geral

Quer insights mais detalhados sobre a performance do seu aplicativo além das métricas integradas do navegador? O painel Performance agora permite que você traga seus próprios dados de performance diretamente para a linha do tempo. Seja você um autor de framework que precisa visualizar processos internos, um desenvolvedor de biblioteca que acompanha o impacto do seu código ou um criador de aplicativos complexos com instrumentação personalizada, a API de extensibilidade de performance oferece as ferramentas para entender o que está acontecendo.

Ao injetar suas medições e eventos personalizados, você pode criar visualizações personalizadas no painel Performance. Imagine ver os eventos do ciclo de vida do componente do framework junto com as métricas de performance padrão do navegador ou acompanhar o fluxo de execução do seu mecanismo de renderização personalizado em perfeita sincronização com o pipeline de renderização do navegador.

Essa API oferece duas abordagens para isso:

1. A console.timeStamp API (estendida para o DevTools)

Essa API oferece um método de alta performance para instrumentar aplicativos e exibir dados de tempo exclusivamente no painel Performance do DevTools. Ela foi projetada para ter uma sobrecarga mínima de execução, o que a torna adequada para instrumentar caminhos frequentes e builds de produção. Ela não adiciona entradas à linha do tempo de performance interna do navegador.

2. A API velocidade do usuário (usando performance.mark e performance.measure)

Essa API aproveita a API velocidade do usuário atual. Ela também adiciona entradas à linha do tempo de performance interna do navegador, permitindo mais análises e integração com outras ferramentas de performance.

Principais vantagens

As duas APIs oferecem:

• Faixas personalizadas:adicione faixas dedicadas e grupos de faixas para representar os aspectos de performance exclusivos do seu código.
• Entradas:preencha essas faixas com entradas que marcam claramente eventos importantes ou a duração de uma operação específica.
• Personalização de cores:use a codificação de cores para distinguir visualmente diferentes tipos de eventos ou medições de relance.

Como escolher a API certa para suas necessidades :

• API console.timeStamp :

  • O impacto da instrumentação na performance é uma preocupação principal, especialmente em builds de produção.
  • Você precisa de uma maneira rápida e eficiente de marcar durações ou eventos sem a necessidade de metadados extras.
  • Você só precisa que os dados sejam visualizados no painel "Performance".

• API Velocidade do usuário (performance.mark, performance.measure) :

  • Use quando precisar armazenar dados extras com cada entrada e quando já estiver usando a API de velocidade do usuário.
  • Você precisa associar dados avançados (dicas de ferramentas, propriedades detalhadas) às suas entradas de performance.
  • Você quer adicionar marcadores visuais para destacar momentos específicos.
  • Você precisa que os dados estejam disponíveis não apenas no DevTools, mas também na linha do tempo de performance interna do navegador para uma análise mais ampla ou outras ferramentas.
  • Você já conhece ou usa a API de velocidade do usuário.

Injetar dados com console.timeStamp

A API console.timeStamp é estendida para permitir a criação de entradas de tempo personalizadas no painel Performance com sobrecarga mínima, especialmente quando o DevTools não está gravando um trace.

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

• label:

  O rótulo da entrada de tempo.

• start (opcional):

  • Se definido como string: o nome de um carimbo de data/hora gravado anteriormente (usando console.timeStamp(timeStampName)).

  • Se definido como número: um carimbo de data/hora em milissegundos em relação a Performance.timeOrigin (por exemplo, extraído com performance.now()) que representa o horário de início da entrada de tempo.

  • Se não estiver definido, o horário atual será usado como horário de início.

• end:

  • Se definido como string: o nome de um carimbo de data/hora gravado anteriormente.

  • Se definido como número: um carimbo de data/hora em milissegundos em relação a Performance.timeOrigin (por exemplo, extraído com performance.now()) que representa o horário de término da entrada de tempo.

  • Se não estiver definido, o horário atual será usado como horário de término.

• trackName:

  O nome da faixa personalizada.

• trackGroup:

  O nome do grupo de faixas.

• color:

  A cor da entrada.

Injetar dados com a API de velocidade do usuário

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 exibidos no painel Performance.

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

• 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 um ponto de referência para criar um performance.measure, não será necessário incluir o objeto devtools em chamadas 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
}

Conferir seus dados na linha do tempo

Para conferir seus dados personalizados na linha do tempo, no painel Performance, verifique se a configuração está ativada: settings Capture settings > check_box Show custom tracks.

Teste nesta página de demonstração. Inicie uma gravação de performance, clique em Add new Corgi na página de demonstração e interrompa a gravação. Você verá uma faixa personalizada no trace que contém eventos com dicas de ferramentas personalizadas, detalhes na guia Summary e resumos de grupos de faixas personalizadas no resumo do trace.

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 console.timeStamp:

// Take a start timestamp
const start = performance.now();

// Measure duration from start to now
console.timeStamp("measure 1", start, undefined, "My Track", "My Group", "primary-light");

// Take an end timestamp
const end = performance.now();

// 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 performance:

Exemplos da API de velocidade do usuário:

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

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

Faixas e entradas personalizadas

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

// Mark used to represent the start of the image processing task
// The start time is defaulted to now
const imageProcessinTimeStart = performance.now();

// ... 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: imageProcessinTimeStart,
  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, juntamente com o texto e as propriedades da dica de ferramenta:

Marcadores

Destaque visualmente 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 seguinte marcador na faixa Timings, juntamente com o texto e as propriedades da dica de ferramenta: