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 aproveita a API User Timings e permite injetar suas medições e eventos diretamente na linha do tempo de performance como uma faixa personalizada ou na faixa Timings. Isso pode ser útil para desenvolvedores de frameworks, bibliotecas e aplicativos complexos com instrumentação personalizada para entender melhor a performance.

Principais recursos

• Faixas personalizadas: crie faixas dedicadas para visualizar seus próprios dados baseados em tempo.
• Entradas: preencha 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 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
}

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

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 preencha-as 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 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 ferramentas: