...

Cabeçalho Server-Timing: compreender os tempos de execução do backend no navegador

O Cabeçalho Server-Timing Envia métricas de backend registadas internamente através de uma resposta HTTP. Podes associá-las à respetiva solicitação nas DevTools do navegador ou lê-las através da API de desempenho. É necessário que a aplicação ou outro componente responsável pela resposta registe e envie os valores. O cabeçalho não é um perfilador automático: só os limites de medição documentados revelam o trabalho que uma duração abrange. Sobreposições, percursos de rede e respostas em cache podem alterar a interpretação.

O que o Server Timing torna visível

Uma página lenta pode perder tempo no navegador, na rota de rede ou durante o processamento no servidor. O Cabeçalho Server-Timing combina estas perspetivas: transmite métricas que um componente de servidor envolvido registou por si próprio, juntamente com uma resposta HTTP. O navegador pode, em seguida, associá-las à respetiva solicitação e apresentá-las.

Para tal, a aplicação tem, por exemplo, de medir a duração de uma operação na base de dados e registar o valor no cabeçalho da resposta. Um proxy ou outro componente responsável pela resposta também pode fornecer métricas. Sem essa instrumentação, o navegador não consegue determinar posteriormente quanto tempo demoraram as diferentes etapas do processamento do lado do servidor.

O cabeçalho é, portanto, um Formato de transporte, não é um profiler automático. Não determina quais as funções internas que devem ser analisadas nem o nível de detalhe com que uma aplicação deve efetuar as medições. Os indicadores apresentados dependem do que o componente responsável regista e autoriza a apresentar.

Para o Desempenho do backend Isto é útil porque um segmento medido pelo próprio utilizador fica visível imediatamente ao lado das informações relativas ao pedido do navegador. Um valor elevado constitui, em primeiro lugar, um ponto de partida para análises mais aprofundadas, mas ainda não é prova de que uma página seja lenta. Por si só, este indicador não explica nem a causa nem todos os outros fatores que influenciam o desempenho web.

Para a utilização prática, precisas, portanto, de ter acesso à aplicação ou a outro componente que possa influenciar a resposta. Se já forem fornecidas métricas, podes, por outro lado, analisá-las no navegador sem teres de alterar tu próprio a configuração do servidor. Mesmo nesse caso, deves esclarecer de onde provêm os valores e o que abrangem efetivamente.

Compreender as métricas e a sintaxe dos cabeçalhos

Uma resposta HTTP pode conter uma ou mais linhas de cabeçalho «Server Timing». Dentro de cada linha, as vírgulas separam as métricas individuais; cada parâmetro é precedido por um ponto e vírgula. Cada métrica necessita de um nome, enquanto a duração e a descrição são opcionais. A duração indicada consta no parâmetro dur e é expresso em milésimos de segundo.

O exemplo seguinte mostra uma linha de cabeçalho de resposta HTTP com duas métricas. Os números são aleatórios e não correspondem a nenhuma medição; a linha é apenas um exemplo de sintaxe e não pressupõe nenhuma aplicação ou configuração de servidor específica.

Código
Server-Timing: db;dur=42.5;desc="Datenbank", render;dur=18.0

Aqui refere-se a db uma métrica com duração e descrição; render tem uma duração, mas não tem descrição. As informações de acordo com desc servem para esclarecimento. Não substituem a documentação relativa ao início e ao fim de cada medição.

Componentes de uma métrica de temporização do servidor
ComponenteSignificadoEstado de obrigatoriedadeExemplo
NomeRefere-se à métricaNecessáriodb
durDuração em milissegundosOpcionaldur=42,5
descDescrição da métricaOpcionaldesc="Base de dados"

Um nome como db por si só, não revela nem a Limites de medição nem o método de medição. Pode referir-se a uma única consulta, a várias consultas somadas ou a uma secção da base de dados definida de outra forma. Só a documentação da instrumentação permite compreender que trabalho está efetivamente incluído nesse valor.

Para que as comparações sejam significativas, deves, por isso, registar o ponto inicial e o ponto final de cada métrica e indicar se esta inclui outras operações parciais. Se, por exemplo, o nome permanecer o mesmo, mas a aplicação passar a incluir consultas adicionais no cálculo do tempo, os valores antigos e os novos não serão facilmente comparáveis. A sintaxe, por si só, não indica essa alteração.

Distinguir o tempo de processamento no backend do tempo de espera do navegador

O tempo de espera visível no navegador e a duração do backend indicada não correspondem necessariamente ao mesmo intervalo de tempo. Uma métrica pode abranger apenas uma parte especificamente selecionada do processamento, enquanto a visualização do navegador mostra outras partes do percurso da solicitação e da resposta. Por isso, valores semelhantes ou diferentes não significam automaticamente que ambas as medições se confirmem ou se contradigam.

Entre o navegador e a aplicação podem existir, por exemplo, percursos de rede e proxies. Também as filas de espera ou as etapas de processamento no backend podem ficar fora dos pontos de medição definidos. Se o navegador esperar mais tempo do que a duração de uma operação na base de dados comunicada, a diferença não pode, por isso, ser atribuída a uma causa específica apenas com base neste único indicador.

Por outro lado, as métricas de temporização do servidor podem sobrepor-se ou estar interligadas. Se uma métrica global medir o processamento de um pedido, incluindo a operação na base de dados, a duração desta já está incluída no valor total. Se somares os dois números, estás a contabilizar esta secção duas vezes; no caso de operações executadas em paralelo, a soma das respetivas durações individuais também pode ser superior ao tempo decorrido.

O cabeçalho não constitui, portanto, um texto automaticamente completo Cascata do processamento. Este transmite indicadores específicos, mas os nomes e as durações, por si só, não estabelecem nem uma sequência temporal nem relações entre as etapas. Para a interpretação, é necessário saber se a instrumentação regista trabalhos separados, intercalados ou que decorrem em simultâneo.

Antes de deduzir uma otimização, define os limites de medição e as condições da consulta em análise. Em seguida, repete consultas semelhantes e verifica se o padrão se repete nas mesmas condições. Desta forma, consegues distinguir melhor um valor isolado que se destaca de um indício recorrente, sem atribuir uma causa apenas com base na métrica.

Verificar a resposta HTML no DevTools

No caso de uma página HTML dinâmica, a aplicação pode registar duas etapas distintas: uma operação na base de dados e a subsequente geração do HTML. A medição deve ser configurada na aplicação ou noutro componente responsável pela resposta. O DevTools apresenta os valores fornecidos, mas não calcula por si próprio os tempos de execução internos.

Define para db o início, imediatamente antes da execução de uma determinada operação da base de dados, e o fim, assim que o resultado dessa operação estiver disponível na aplicação. Para render Este período começa imediatamente antes da criação do HTML e termina assim que o código HTML final estiver pronto para a resposta. Indique se, por exemplo, o carregamento de modelos está incluído neste período.

Supondo que ambos os passos estejam concluídos antes do envio dos cabeçalhos de resposta: nesse caso, a resposta poderia Server-Timing: db;dur=42.5, render;dur=18.0 incluídos. Os números são escolhidos arbitrariamente e não correspondem a qualquer medição. Só os pontos inicial e final documentados é que os tornam comparáveis de forma significativa para uma análise posterior.

No Chrome, abre as Ferramentas do Desenvolvedor e a secção «Rede». Atualiza a página, seleciona a solicitação do documento na lista de solicitações e verifica, na secção «Cabeçalhos», o cabeçalho bruto recebido. Em «Timing», pode então visualizar a apresentação dos valores de temporização do servidor comunicados; a apresentação exata pode variar consoante o navegador.

Um chamativo Valor individual É um ponto de partida, não uma prova de uma causa geral. Repete consultas semelhantes e regista, por exemplo, a página utilizada, o estado da cache e as alterações na aplicação. Desta forma, poderás identificar melhor se existe um padrão recorrente ou se uma resposta específica se desvia da norma.

Ler os tempos da API sem contagem dupla

No caso de uma API, a aplicação pode registar não só todo o processamento, mas também a espera por um serviço externo. O que é decisivo neste contexto é a Limite de medição: Se o tempo total começar ao entrar no manipulador da API e terminar quando a resposta deste estiver pronta para ser apresentada, a chamada externa pode estar totalmente incluída nesse período.

No exemplo a seguir, escolhido livremente, a duração externa começa imediatamente antes do envio do pedido ao serviço e termina assim que a resposta deste estiver disponível na aplicação. Os valores servem apenas para efeitos de cálculo e não constituem uma medição. A tabela descreve expressamente intervalos de tempo sobrepostos, e não dois pacotes de trabalho independentes.

Exemplo arbitrário de métricas de API aninhadas
MétricasLimites de medição no exemploDuração
Processamento globalEntrada no Handler até que a resposta esteja disponível120 ms
Chamada externaEnvio do pedido até que seja recebida a resposta do serviço80 ms

O cálculo de 120 ms mais 80 ms dá, de facto, 200 ms, mas, neste caso, seria um Dupla contagem: Os 80 ms já se encontram dentro dos 120 ms. Matematicamente, restam 40 ms do intervalo total fora da chamada externa. No entanto, o cabeçalho, por si só, não explica que tipo de trabalho ou tempo de espera este intervalo restante inclui.

Ilustração gerada por IA de uma área circular menor dentro de uma maior, como símbolo de tempos de API intercalados
Ilustração gerada por IA: A duração de uma chamada externa pode já estar incluída no tempo total de processamento.

Mesmo as dependências paralelas não podem ser simplesmente somadas para obter um tempo total decorrido. Se, por exemplo, duas chamadas forem executadas em simultâneo e cada uma demorar 80 ms, as suas durações individuais somam 160 ms, embora os seus intervalos de tempo possam sobrepor-se em grande parte. Sem informação sobre o início e o fim, não é possível determinar o grau real de sobreposição apenas a partir das durações.

Para determinar qual o serviço que desencadeou qual a chamada seguinte, o rastreio distribuído complementa os valores dos cabeçalhos. O Server-Timing pode associar durações selecionadas à resposta do navegador, mas, por si só, não descreve as relações causais completas entre os serviços. Ao comparar, certifica-te de que o rastreio e o cabeçalho se referem às mesmas operações e limites.

Ler o Server-Timing através de JavaScript

O API de Desempenho torna os dados de temporização do servidor disponíveis também a nível de programação. Uma entrada de navegação descreve o carregamento do documento atual; a sua propriedade serverTiming contém as métricas comunicadas disponíveis para esse efeito. Trata-se de uma seleção diferente da de uma entrada relativa a um recurso carregado posteriormente ou a uma chamada à API.

Execute o seguinte código JavaScript na consola do navegador, na página que pretende analisar. Este código seleciona a primeira entrada de navegação existente e apresenta a sua lista de tempos de servidor sob a forma de tabela. O código apenas lê os valores já disponíveis: não altera a configuração do servidor nem realiza qualquer teste de carga.

Código
const navigation = performance.getEntriesByType("navigation")[0];
console.table(navigation?.serverTiming ?? []);

Se não existir nenhuma entrada de navegação ou se esta não fornecer métricas acessíveis, o exemplo apresenta uma lista vazia. Isso não significa necessariamente que a página seja rápida ou lenta, nem que o servidor não disponha de instrumentação. Verifica, em primeiro lugar, o cabeçalho da resposta e se a entrada selecionada descreve efetivamente o pedido pretendido.

Para um recurso carregado posteriormente, precisas, em vez disso, do correspondente Registo de recursos. Entre as entradas do tipo resource podes identificar, com base no nome, o pedido em questão e o seu serverTiming-Analisar a propriedade. Ao aceder repetidamente à mesma morada, tens de ter em atenção qual é a entrada específica que estás a comparar.

No caso de recursos que abrangem várias origens, a autorização adequada através do `Timing-Allow-Origin` também influencia se a API de desempenho disponibiliza as informações de tempo. A compatibilidade do navegador e o ambiente em questão também podem influenciar o resultado. Por isso, compara uma lista vazia com o cabeçalho bruto antes de efetuares alterações na aplicação.

Partilhas no Origin e dados confidenciais

Ao aceder através da API de desempenho, a origem da página que efetua a chamada é determinante. Se um recurso provier de uma origem diferente, a resposta desse recurso deve ser Timing-Allow-Origin configurar corretamente a origem de origem, para que o JavaScript possa ler as informações de temporização relevantes, incluindo a temporização do servidor. A autorização CORS, por si só, não substitui esta autorização adicional.

A origem concreta limita a autorização à origem indicada. O símbolo de substituição * Por outro lado, permite, em princípio, que todas as origens consultem as informações de temporização em questão através da API de desempenho. Por isso, opta pela autorização mais restrita se apenas uma aplicação conhecida necessitar dos valores e verifica-os na resposta de recursos efetivamente fornecida.

A autorização «Origin» não torna um cabeçalho de resposta confidencial. Quem receber a resposta HTTP pode, em princípio, analisar o seu conteúdo. Por isso, não divulgue dados de acesso, informações pessoais nem nomes de anfitriões internos em nomes de métricas e descrições. Mesmo os tempos de execução com granularidade elevada podem permitir deduzir processos internos; divulga apenas valores cuja utilidade e risco tenhas ponderado conscientemente.

Verifica também a análise nos navegadores que a tua aplicação deve suportar: o suporte a detalhes específicos e os requisitos relativos a contextos seguros podem variar. Para garantir a segurança geral das respostas, é necessário, além disso, cabeçalhos de segurança adequados para servidores Web são relevantes; no entanto, não substituem nem a verificação da autorização de divulgação nem a decisão sobre quais os valores de medição que podem ser tornados públicos.

Verificar valores em falta e efeitos de cache

Se a lista com os valores de Server Timing estiver vazia, começa pela solicitação específica na secção de rede do DevTools. Verifica, em «Headers», se a resposta enviada contém, de todo, um Server-Timing- Verifique se o cabeçalho está presente e quais os nomes que nele constam. Se estiver em falta, analise a instrumentação e eventuais alterações causadas por componentes intermédios, em vez de deduzir a velocidade a partir da lista vazia.

Se o cabeçalho bruto existir, verifica, em seguida, o Registo de desempenho: A entrada de navegação descreve o carregamento do documento, enquanto uma chamada à API ou outro recurso requer uma entrada de recurso correspondente. No caso de recursos entre domínios, deve também verificar a autorização através de Timing-Allow-Origin bem como a compatibilidade com o navegador utilizado. Uma lista vazia, por si só, não indica nem a falta de instrumentação nem uma resposta rápida ou lenta.

Mesmo um valor já existente precisa de contexto. Uma CDN ou um proxy podem fornecer as suas próprias métricas; ao mesmo tempo, uma resposta, incluindo os cabeçalhos, pode provir de uma cache. Nesse caso, uma métrica de origem gerada anteriormente não descreve necessariamente o trabalho do servidor de origem para o pedido atual. Por isso, documenta Estado e origem da cache independentemente da duração.

Imagem simbólica gerada por IA de um cabo de rede ligado a um switch, em grande plano lateral
Imagem ilustrativa gerada por IA: podem existir outros componentes de rede entre o navegador e a aplicação.

Verifica, na configuração específica, qual o componente que define, transmite ou altera o cabeçalho e como este lida com as respostas armazenadas em cache. Em seguida, compara as solicitações com o estado conhecido da cache, na medida em que a tua infraestrutura o permita. As diferenças entre estas respostas são indicações úteis, mas, sem conhecimento dos respetivos limites de medição, não constituem ainda prova de uma causa específica.

Troncos, reboques e escolha de ferramentas

O Server-Timing complementa outras formas de diagnóstico, em vez de as substituir. A escolha adequada depende se pretendes compreender uma única solicitação do navegador, recolher valores existentes de forma programática ou analisar relações entre vários serviços. A visão geral que se segue distingue os respetivos ganhos de conhecimento dos seus pré-requisitos e limitações.

Comparação de métodos de diagnóstico para respostas HTTP
FerramentaConclusãoPré-requisitoFronteira
DevToolsVerificar pedidos individuais e horários comunicadosConsulta do navegador com métricas relevantesNão há análise automática das causas
API de DesempenhoLer os valores de temporização existentes através de JavaScriptRegisto adequado e, se for caso disso, autorização de origemNão existe um fluxo de trabalho completo entre serviços
Registos do servidorAnalisar os horários registados no servidorFormato de registo adequado e acesso aos registosOs limites de medição e as unidades devem ser verificados
Rastreio distribuídoAnalisar as relações entre os serviços envolvidosInstrumentação e atribuição dos traçosCustos adicionais de exploração e instrumentação

No caso de um indicador cujo valor só é conhecido após a conclusão da resposta, uma entrada de registo pode ser mais adequada do que um cabeçalho de resposta normal. O NGINX, por exemplo, regista request_time e upstream_response_time em segundos, com resolução em milissegundos. O Server-Timing, por sua vez, utiliza milissegundos: um valor em segundos tem de ser multiplicado por 1 000. Antes de fazer uma comparação, verifica também quando é que cada medição começa e termina.

Em Streaming é possível que a duração total do corpo da resposta ainda não esteja definida no momento do envio dos cabeçalhos normais. A especificação permite também o Server Timing como HTTP Trailer. No entanto, esta não é uma solução universal: a Fetch API não disponibiliza os Trailers, e a sua apresentação nas ferramentas de desenvolvimento tem de ser verificada separadamente para cada navegador.

Para obter comparações mais fiáveis, repete consultas semelhantes em condições documentadas: regista, por exemplo, o ponto final, o estado da cache e as alterações relevantes no sistema. Analise vários valores em vez de uma única consulta e investigue mais a fundo as diferenças suspeitas através de registos ou rastreios. Desta forma, fica claro qual a observação que está efetivamente abrangida por cada medição.

Um ambiente de teste baseado no navegador pode ajudar a experimentar configurações da aplicação, mas não reproduz automaticamente os percursos de rede e os serviços de servidor que serão utilizados na operação posterior. O mesmo se aplica a WordPress Playground no navegador. Além disso, deves verificar as informações relativas a uma configuração concreta de alojamento e back-end num ambiente o mais próximo possível do ambiente de produção.

Fontes e estado atual dos conhecimentos

Estado da pesquisa:

Data da pesquisa: 13 de novembro de 2026. A apresentação no navegador e o suporte a determinadas funcionalidades podem variar; os exemplos não incluem medições próprias.

https://www.w3.org/TR/server-timing/

https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming/serverTiming

https://developer.chrome.com/docs/devtools/network?hl=en

https://developer.chrome.com/docs/devtools/performance/reference/

https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Timing-Allow-Origin

https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Server-Timing

https://docs.nginx.com/nginx/admin-guide/monitoring/logging/

Artigos actuais

Ilustração gerada por IA de intervalos de medição sobrepostos e entrelaçados sobre um fundo escuro
Administração

Medir o tempo de execução do PHP separadamente da rede e do front-end

Um temporizador PHP, os tempos do navegador e o tempo do servidor mostram diferentes fases de um pedido. Desta forma, podes comparar os seus limites e identificar de forma específica os pontos de estrangulamento na base de dados, na rede e no front-end.