Partilhar via

Personalizar o perfil de desempenho com APIs de extensibilidade

Conteúdo detalhado:

Visão Geral

A Ferramenta de desempenho pode apresentar os seus próprios dados de desempenho, além das métricas incorporadas do browser. Apresentar os seus próprios dados de desempenho personalizados na ferramenta Desempenho pode ser útil em casos como quando:

  • Criar uma estrutura e tem de visualizar processos internos.
  • Desenvolver uma biblioteca e pretende controlar o impacto do seu código.
  • Criar uma aplicação Web complexa com muito processamento do lado do cliente.

As APIs de extensibilidade de desempenho permitem compreender o que está a acontecer no seu código.

Ao injetar medidas e eventos personalizados, pode criar visualizações personalizadas na ferramenta Desempenho .

As APIs de extensibilidade de desempenho são duas abordagens para o conseguir:

  1. A console.timeStamp() API (expandida para DevTools)

    Esta API fornece um método de elevado desempenho para instrumentar aplicações e apresentar dados de tempo exclusivamente à ferramenta Desempenho em DevTools. Foi concebido para um overhead de tempo de execução mínimo, tornando-o adequado para instrumentar caminhos quentes e compilações de produção. Não adiciona entradas ao linha do tempo de desempenho interno do browser.

  2. A API de Temporizações do Utilizador (com performance.mark() e performance.measure())

    Esta API tira partido da API de Temporizações de Utilizador existente. Também adiciona entradas ao linha do tempo de desempenho interno do browser, permitindo uma análise e integração adicionais com outras ferramentas de desempenho; veja APIs de Desempenho no MDN.

Exemplo de faixas personalizadas na ferramenta Desempenho

A captura de ecrã acima tem as seguintes caixas adicionadas, para realçar os resultados:

  • Caixa vermelha na faixa Temporizações : performance.mark(). Os marcadores personalizados são Iniciar filtragem, Filtragem concluída e Fotografia selecionada. As linhas tracejadas verticais abrangem todas as faixas.

  • Caixa azul na faixa de criação de Fotografias personalizada: performance.measure()

  • Caixa verde na faixa do carimbo de data/hora personalizada da Consola: console.timeStamp()

Principais benefícios

Ambas as APIs oferecem:

  • Faixas Personalizadas: Adicione faixas dedicadas e controle grupos, num perfil de desempenho, para representar os aspetos de desempenho exclusivos do seu código.

  • Entradas: Preencha estas faixas com entradas que marcam claramente eventos importantes ou a duração de uma operação específica.

  • Personalização de Cores: Utilize a codificação de cores para distinguir visualmente diferentes tipos de eventos ou medidas de relance.

Escolher a API certa

A console.timeStamp() API de Temporizações do Utilizador e servem necessidades diferentes.

Utilize a console.timeStamp() API quando:

  • O impacto no desempenho da instrumentação é uma preocupação principal, especialmente nas compilações de produção.

  • Precisa de uma forma rápida e eficiente de marcar durações ou eventos sem a necessidade de metadados adicionais.

  • Só precisa que os dados sejam visualizados na ferramenta Desempenho .

Utilize a API de Temporizações do Utilizador (performance.mark() ou performance.measure()) quando:

  • Tem de armazenar dados adicionais com cada entrada e quando já estiver a utilizar a API de Temporizações do Utilizador.

  • Tem de associar dados avançados (descrições, propriedades detalhadas) às entradas de desempenho.

  • Quer adicionar marcadores visuais para realçar momentos específicos.

  • Precisa que os dados estejam disponíveis não só nas DevTools, mas também no desempenho interno do browser linha do tempo para uma análise mais ampla ou outras ferramentas.

  • Já está familiarizado ou a utilizar a API de Temporizações do Utilizador.

A demonstração da Galeria de Fotografias demonstra todas estas APIs.

Injetar os seus dados com console.timeStamp()

A console.timeStamp() API é expandida para permitir a criação de entradas de temporização personalizadas na ferramenta Desempenho com sobrecarga mínima, especialmente quando o DevTools não está a registar um rastreio.

Sintaxe:

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

  • label:

    A etiqueta para a entrada de temporização.

  • start (opcional):

    • Se definido como uma cadeia: o nome de um carimbo de data/hora registado anteriormente (com console.timeStamp(timeStampName)).

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

    • Se não for definida, a hora atual é utilizada como hora de início.

  • end:

    • Se definido como uma cadeia: o nome de um carimbo de data/hora registado anteriormente.

    • Se definido como um número: um carimbo de data/hora em milissegundos em relação a Performance.timeOrigin (por exemplo, tomado com performance.now()) que representa a hora de fim da entrada de temporização.

    • Se não for definida, a hora atual é utilizada como hora de fim.

  • trackName:

    O nome da faixa personalizada.

  • trackGroup:

    O nome do grupo de faixas.

  • color:

    A cor da entrada.

Veja também:

Injetar os seus dados com a API de Temporizações do Utilizador

Para injetar dados personalizados, inclua um devtools objeto na propriedade detail do performance.mark() método ou na propriedade detail do performance.measure() método. A estrutura deste devtools objeto determina a forma como os seus dados são apresentados na ferramenta Desempenho .

  • Utilize performance.mark() para registar um evento instantâneo ou carimbo de data/hora no linha do tempo. 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 inclui um devtools objeto na detail propriedade, a ferramenta Desempenho mostra um marcador personalizado na faixa Temporizações .

  • Utilize performance.measure() para medir a duração de uma tarefa ou processo. Quando inclui um devtools objeto na propriedade, a detail ferramenta Desempenho mostra entradas de medida personalizadas no linha do tempo numa faixa personalizada. Se estiver a utilizar performance.mark() como ponto de referência para criar um performance.measure(), não precisa de incluir o devtools objeto nas performance.mark() chamadas.

devtools objeto

Estes tipos definem a estrutura do devtools objeto para diferentes funcionalidades 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 os dados personalizados no perfil de desempenho

Para ver os seus dados personalizados num perfil de desempenho registado, na ferramenta Desempenho , utilize primeiro uma das APIs de extensibilidade de desempenho e, em seguida, registe um perfil.

Para gravar um perfil e ver os dados de desempenho personalizados da página de demonstração da Galeria de Fotografias:

  1. Abra a página Web de demonstração da Galeria de Fotografias numa nova janela ou separador.

    Em alternativa, para poder modificar o código de exemplo:

    1. Clone o repositório "MicrosoftEdge/Demos", por Clone o repositório Demos do Edge para a unidade em Código de exemplo para DevTools.
    2. Inicie um servidor localhost no diretório clonado /demos/ , por Iniciar o servidor localhost, em Código de exemplo para DevTools.
    3. No browser, aceda a http://localhost:8080/photo-gallery/ ou equivalente numa nova janela ou separador.

  2. Clique com o botão direito do rato na página Web e, em seguida, selecione Inspecionar.

    O DevTools é aberto.

  3. Em DevTools, selecione a ferramenta Desempenho (ícone desempenho).

  4. Na ferramenta Desempenho , clique no botão Definições de captura (ícone Definições de captura) e, em seguida, certifique-se de que a caixa de verificação Mostrar faixas personalizadas está selecionada:

    A caixa de verificação

  5. Na lista pendente limitação da CPU , selecione 4x abrandamento – recomendado.

    É adicionado um indicador de aviso de limitação ao separador Desempenho .

  6. Atualize a página para limpar as seleções.

  7. Clique no botão Gravar (ícone Gravar).

  8. Na parte superior da página de demonstração, no menu pendente Câmara (ícone câmara) à esquerda, mude de Tudo para Apple iPhone 12.

  9. Altere o filtro Câmara novamente para Tudo.

  10. Clique na primeira fotografia.

    A fotografia expande-se.

  11. Em DevTools, clique no botão Parar .

    O perfil é apresentado.

  12. Clique em Personalizar e controlar DevTools (personalizar e controlar o ícone DevTools) e, em seguida, junto a Localização da Dock, selecione Desancorar numa janela separada (Desancorar em ícone de janela separado).

    As DevTools são desanexadas na sua própria janela, pelo que é mais fácil ver mais dados.

  13. Desloque-se para baixo até ao grupo Temporizações de desempenho personalizadas — Faixa personalizada e expanda-o.

  14. Expanda as faixas personalizadas:

    • Criação de fotografias
    • Faixa de carimbo de data/hora da consola

  15. Utilize o rato e as teclas de seta para deslocar e ampliar o perfil, para apresentar as medidas de desempenho personalizadas:

    Faixas personalizadas expandidas

  16. Paire o cursor sobre um marcador numa faixa personalizada, como um marcador de Carregamento na Faixa de carregamento .

    É apresentada uma descrição personalizada, incluindo duração e legenda.

  17. Selecione um marcador numa faixa personalizada.

    No separador Resumo , na parte inferior da ferramenta Desempenho , são apresentados detalhes para o marcador.

O código que define estas medidas de desempenho personalizadas é apresentado em Adicionar faixas e entradas personalizadas ao linha do tempo (performance.measure()), abaixo.

Exemplos de código

Seguem-se alguns exemplos de como utilizar a API para adicionar os seus próprios dados à ferramenta Desempenho através de cada mecanismo disponível.

console.timeStamp() Exemplos de API

Por exemplo, na galeria de fotografias/gallery.js, a loadPhoto() função define um startTime e endTime ao chamar performance.now()e, em seguida, chama console.timeStamp() para mostrar o tempo que demora a carregar uma fotografia depois de clicar nessa fotografia:

// Load a photo and return a promise that resolves when the photo is loaded.
function loadPhoto(fileName) {
  // Record the start time of the photo loading for performance tracking.
  const startTime = performance.now();

  return new Promise(resolve => {
    // Load the image by creating a new image element.
    const imageEl = document.createElement("img");
    imageEl.src = fileName;

    // Listen for the load event to resolve the promise when the image is loaded.
    imageEl.addEventListener('load', () => {
      // Record the end time of the photo loading.
      const endTime = performance.now();

      // Display the photo loading duration in the Performance tool, by using console.timeStamp.
      console.timeStamp("Loading photo",              // label
                        startTime,                    // start
                        endTime,                      // end
                        "Console timestamp track",    // trackName
                        "Custom performance timings", // trackGroup
                        "primary-dark");              // color

      resolve(imageEl);
    }, { once: true });
  });
}

Para ver o perfil resultante:

  1. Siga os passos indicados em Ver os seus dados personalizados no perfil de desempenho acima.

  2. Desloque-se para baixo até ao grupo Temporizações de desempenho personalizadas — Faixa personalizada e expanda-o.

  3. Expanda a faixa de carimbo de data/hora da Consola.

  4. Utilize o rato e as teclas de seta para deslocar e ampliar o perfil, para apresentar as medidas de desempenho personalizadas:

    Uma faixa personalizada com entradas personalizadas adicionadas com a API console.timeStamp

    O evento A carregar fotografias foi criado com console.timeStamp(). Este evento tem uma duração, porque é criado com uma hora de início e de fim. Este evento corresponde ao tempo que demora a carregar a versão em ecrã inteiro da fotografia em que clicou.

Veja também:

Exemplos da API de Temporizações do Utilizador

Nas secções seguintes, veja os exemplos de código que mostram como adicionar o seguinte ao linha do tempo de desempenho:

Adicionar faixas e entradas personalizadas ao linha do tempo (performance.measure())

Crie faixas personalizadas e preencha-as com entradas para visualizar os seus dados de desempenho numa faixa personalizada.

Por exemplo, na galeria de fotografias/gallery.js, a populateGallery() função define um startTime e endTime ao chamar performance.now()e, em seguida, chama performance.measure() para mostrar o tempo necessário para criar uma fotografia na galeria:

// Populate the gallery with the given images.
function populateGallery(images) {
  // Empty the existing gallery elements.
  galleryEl.innerHTML = '';

  // Iterate over the images.
  images.forEach(({ file, user, description, w, h, meta }) => {
    // Record the start time of this image creation for performance tracking.
    const startTime = performance.now();

    // Create the necessary DOM elements, and append them to the gallery.
    const liEl = createImageDOM(file, user, description, meta, w, h);
    galleryEl.appendChild(liEl);

    // Record the end time of this image creation.
    const endTime = performance.now();

    // Display the image creation duration in the Performance tool
    // by using the performance.measure API, with the devtools
    // object.
    performance.measure(`Image ${file} created`, {
      start: startTime,
      end: endTime,
      detail: {
        devtools: {
          dataType: "track-entry",
          color: "primary",
          trackGroup: "Custom performance timings",
          track: "Photo creation",
          properties: [
            ['File', file],
            ['Width', w],
            ['Height', h],
            ['User', user],
          ],
          tooltipText: `Image ${file} created`
        }
      },
    });
  });
}

Para ver o perfil resultante:

  1. Siga os passos indicados em Ver os seus dados personalizados no perfil de desempenho acima.

  2. Desloque-se para baixo até ao grupo Temporizações de desempenho personalizadas — Faixa personalizada e expanda-o.

  3. Expanda a faixa Criação de fotografias.

  4. Utilize o rato e as teclas de seta para deslocar e ampliar o perfil para apresentar as medidas de desempenho personalizadas.

    Isto resulta na seguinte entrada de faixa personalizada no linha do tempo de desempenho, juntamente com o texto e as propriedades da descrição:

    A faixa personalizada de criação de fotografias

    Os eventos criados por performance.measure() têm uma duração curta, pelo que tem de ampliar para os ver no perfil. Cada um destes eventos regista a criação de uma imagem, o que acontece quando altera o valor do filtro (lista pendente) e quando toda a IU da galeria é atualizada.

    Os eventos de criação de Fotografias são apresentados entre as Start filtering marcas de desempenho e Done filtering resultantes ( performance.mark() abrangidas na secção seguinte):

    A marca de filtragem Iniciar e a marca de filtragem Concluído

Veja também:

Adicionar marcadores à faixa Temporizações (performance.mark())

Realce visualmente pontos de interesse específicos no linha do tempo com marcadores personalizados que abrangem todas as faixas.

Por exemplo, na galeria de fotografias/gallery.js, um serviço de escuta de eventos input processa eventos nas listas pendentes de filtros da página de demonstração. O serviço de escuta de eventos chama performance.mark() duas vezes: antes de o novo filtro ser aplicado e depois de o novo filtro ter sido aplicado:

// Handle input events on the filter selects.
addEventListener('input', e => {
  // Check if the input event is from a filter select.
  // If not, return early.
  const filter = e.target.closest('.filter select');
  if (!filter) {
    return;
  }

  // Add a mark in the Performance tool's recorded profile to
  // indicate that a filter will be applied.
  performance.mark("Start filtering", {
    detail: {
      devtools: {
        dataType: "marker",
        color: "secondary",
        properties: [
          ['Filter Value', filter.value]
        ],
        tooltipText: "Start filtering"
      }
    }
  });

  // Reset the other filters.
  filterEl.querySelectorAll('.filter select').forEach(select => {
    if (select !== filter) {
      select.selectedIndex = 0;
    }
  });

  // Apply the filter based on the selected value.
  filterBy(filter);

  // Add a mark in the Performance tool's recorded profile to
  // indicate that a filter was applied.
  performance.mark("Done filtering", {
    detail: {
      devtools: {
        dataType: "marker",
        color: "tertiary",
        properties: [
          ['Filter Value', filter.value]
        ],
        tooltipText: "Done filtering"
      }
    }
  });
});

// Handle click events on photos.
addEventListener('click', e => {
  const clickedPhoto = e.target.tagName === 'IMG' && e.target.closest('.photo');
  if (!clickedPhoto) {
    return;
  }

  // Add a mark in the Performance tool's recorded profile to
  // indicate that a photo was clicked.
  performance.mark("Photo selected", {
    detail: {
      devtools: {
        dataType: "marker",
        color: "secondary-dark",
        properties: [
          ['photo', clickedPhoto.src]
        ],
        tooltipText: "Photo selected"
      }
    }
  });

  selectPhoto(clickedPhoto);
});

Para ver o perfil resultante:

  1. Siga os passos indicados em Ver os seus dados personalizados no perfil de desempenho acima.

  2. Utilize o rato e as teclas de seta para deslocar e ampliar o perfil para apresentar as medidas de desempenho personalizadas.

    A faixa Temporizações apresenta a opção Iniciar filtragem, Filtragem concluída e Marcadores personalizados selecionados por Fotografia :

    Marcadores personalizados na faixa Temporizações

    Os eventos (marcadores) criados por performance.mark() não têm duração; marcam apenas alguns eventos interessantes num perfil: o início e o fim de uma alteração de filtro (utilizando os menus pendentes da página de demonstração) e o momento em que uma fotografia foi selecionada (o marcador Fotografia selecionada ).

Veja também:

Confira também

MDN:

Demonstrações:

Observação

Partes desta página são modificações baseadas no trabalho criado e partilhado pela Google e utilizado de acordo com os termos descritos na Licença Internacional Creative Commons Attribution 4.0. A página original encontra-se aqui e é da autoria de Andrés Olivares e Sofia Emelianova.

Licença Creative Commons Este trabalho é licenciado ao abrigo de uma Licença Internacional creative Commons Attribution 4.0.

  • Last updated on