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, que permite adicionar seus próprios dados personalizados à linha do tempo de performance.

Essa API usa a API User Timing e permite injetar medições e eventos diretamente na linha do tempo de performance como uma faixa personalizada ou no acompanhamento Timing. Isso pode ser útil para que os desenvolvedores de frameworks, bibliotecas e aplicativos complexos com instrumentação personalizada tenham uma compreensão mais abrangente do desempenho.

Principais recursos

• Faixas personalizadas: crie faixas dedicadas para visualizar seus próprios dados com base no tempo.
• Entradas: preencha as faixas com entradas que representam eventos ou medições.
• Dicas e detalhes: ofereça contexto para as entradas com dicas personalizáveis e visualizações detalhadas.
• Marcadores: destaque momentos específicos na linha do tempo com marcadores visuais.

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 gravar 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 Desempenho mostra um marcador personalizado na linha do tempo.

• 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. 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
}

Conferir seus dados na linha do tempo

Para acessar seus dados personalizados na linha do tempo, no painel Desempenho, ative as configurações Configurações de captura > check_box Dados de extensão.

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. Você verá uma faixa personalizada no trace contendo eventos com dicas e detalhes personalizados na guia Resumo.

Exemplos de código

Nas próximas seções, consulte os exemplos de código que mostram como adicionar os seguintes itens ao cronograma de desempenho:

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

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 an image processing task
performance.mark("Image Processing Start");

// ... later in your code

// Track entry representing the completion of image processing
// with additional details and a tooltip
performance.measure("Image Processing Complete", "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 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 marcador a seguir na faixa Timings, com o texto e as propriedades da dica de ferramenta: