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: forneça um contexto amplo 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 seus dados são exibidos no painel Performance.

• Use performance.mark para registrar um evento instantâneo ou um 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 Desempenho 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 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
}

Ver 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. 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 o seguinte ao cronograma de desempenho:

• Faixas e entradas personalizadas no cronograma
• 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 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 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 Timing, com o texto e as propriedades da dica: