Como Perfilhar a Latência de Requisições da API do Notion para Integração Personalizada

Ao criar uma integração personalizada com a API do Notion, respostas lentas podem prejudicar seu fluxo de trabalho. Você pode notar que consultas ao banco de dados levam vários segundos ou que atualizações de página demoram para concluir. Essa latência geralmente vem de chamadas de API ineficientes, limitação de taxa ou atrasos de rede entre seu servidor e os servidores do Notion. Este artigo explica como medir e perfilhar cada requisição da API para identificar o gargalo exato e otimizar sua integração.

Por que a Latência da API do Notion Varia Entre Requisições

A latência da API do Notion é o tempo total entre o envio de uma requisição e o recebimento da resposta completa. Esse atraso consiste em três componentes principais: tempo de ida e volta da rede, tempo de processamento do servidor do Notion e tempo de transferência da resposta. O tempo de ida e volta da rede depende da sua distância geográfica até os servidores do Notion, da qualidade da sua conexão com a internet e da velocidade de resolução DNS. O tempo de processamento do servidor do Notion varia conforme o endpoint — consultar um banco de dados com 5000 linhas leva mais tempo do que buscar uma única página. A limitação de taxa também pode adicionar atrasos artificiais quando você excede 3 requisições por segundo para uma única integração.

A API do Notion retorna um cabeçalho de resposta especial chamado x-notion-request-timing. Esse cabeçalho contém um único número de ponto flutuante representando os milissegundos que os servidores do Notion gastaram processando sua requisição. Ao comparar esse tempo de servidor com seu tempo total medido, você pode separar atrasos de rede de atrasos no lado do servidor. Se o tempo total é 1200 ms e o tempo de servidor é 200 ms, a rede é responsável por 1000 ms da latência.

Causas Comuns de Alta Latência

Três padrões causam a maioria dos problemas de latência. Primeiro, buscar muitas propriedades ou linhas em uma única consulta ao banco de dados força o Notion a serializar grandes payloads JSON. Segundo, fazer muitas requisições sequenciais em vez de paralelas acumula a sobrecarga de rede. Terceiro, executar sua integração de uma região distante dos servidores do Notion, como Austrália quando o endpoint mais próximo está nos Estados Unidos, adiciona 200 a 400 ms por requisição.

Passos para Medir a Latência de Requisições da API do Notion

Você pode perfilhar a latência usando três métodos: temporização no lado do cliente em seu código, inspeção de cabeçalhos de resposta e uso das Ferramentas do Desenvolvedor do navegador ao testar via playground da API do Notion. Os passos a seguir assumem que você está usando Node.js com o SDK oficial do Notion ou chamadas fetch puras.

1. Adicione console.time e console.timeEnd em torno de cada chamada de API
   No seu script Node.js, envolva cada requisição à API do Notion com console.time('consultar-banco') antes da chamada e console.timeEnd('consultar-banco') após receber a resposta. O console registra o tempo decorrido em milissegundos. Use um rótulo único para cada endpoint para identificar chamadas lentas.
2. Leia o cabeçalho de resposta x-notion-request-timing
   Ao usar fetch, acesse response.headers.get('x-notion-request-timing') após a requisição ser concluída. Esse valor é o tempo de processamento do servidor em milissegundos. Para o SDK do Notion, inspecione o objeto de resposta bruto definindo logLevel: 'info' na configuração do cliente.
3. Calcule a latência de rede subtraindo o tempo do servidor do tempo total
   Subtraia o valor de x-notion-request-timing da sua medição de console.timeEnd. Se a diferença for maior que 300 ms, os atrasos de rede são o fator dominante. Se o tempo do servidor estiver acima de 1000 ms, o gargalo está no lado do Notion.
4. Use o Playground da API do Notion no seu navegador
   Abra a página de referência da API do Notion em developers.notion.com, autentique-se com sua integração e envie uma requisição de teste. Abra as Ferramentas do Desenvolvedor do seu navegador, vá para a aba Network e encontre a requisição para api.notion.com. A aba Timing mostra um waterfall com consulta DNS, conexão TCP, handshake TLS, requisição enviada, espera (processamento do servidor) e download do conteúdo.
5. Execute múltiplas requisições e calcule a latência média
   Crie um script que envie a mesma requisição 10 vezes com uma pausa de 1 segundo entre cada. Registre cada tempo total e tempo de servidor, depois calcule a média. Isso suaviza picos de rede transitórios e fornece uma linha de base confiável.

Usando o SDK do Notion para Temporização Automática

O SDK oficial do Notion para JavaScript não expõe a latência por padrão, mas você pode criar uma função wrapper que intercepta cada requisição. Defina uma função chamada requisicaoTemporizada que registra um timestamp de início, chama o método do SDK, registra um timestamp de fim, lê o cabeçalho da resposta e registra todos os três valores. Substitua cada chamada do SDK por este wrapper.

Se a Perfilhagem Mostrar Alto Tempo no Lado do Servidor

Quando x-notion-request-timing excede consistentemente 1000 ms, o problema está nos servidores do Notion. Isso é raro, mas pode acontecer com bancos de dados grandes ou consultas filtradas complexas. O primeiro passo é reduzir o número de propriedades retornadas. Use o parâmetro filter_properties na sua consulta ao banco de dados para solicitar apenas as colunas necessárias. Se você precisar de todas as propriedades, pagine com um tamanho de página menor, como 25 em vez de 100.

Consultar um Banco de Dados Retorna Dados Lentamente

Se uma consulta ao banco de dados levar mais de 3 segundos, verifique o número de linhas. Bancos de dados do Notion com mais de 10.000 linhas podem causar altos tempos de servidor. Adicione um filtro para restringir o conjunto de resultados antes da consulta. Por exemplo, filtre por um intervalo de datas ou por uma propriedade de status. Isso reduz o trabalho que o Notion precisa fazer para serializar a resposta.

Limitação de Taxa Adiciona Respostas Atrasadas

Quando você excede 3 requisições por segundo, o Notion retorna HTTP 429 com um cabeçalho Retry-After. Sua temporização no lado do cliente mostrará um tempo total de vários segundos porque seu código espera antes de tentar novamente. Verifique seus logs em busca de respostas 429. Se você as encontrar, implemente backoff exponencial com um tempo máximo de espera de 30 segundos. Também agrupe suas gravações em uma única requisição quando possível, usando o endpoint append block children com múltiplos blocos.

Fatores de Latência da API do Notion Comparados

Fator	Impacto Típico	Como Medir
Tempo de ida e volta da rede	100–400 ms por requisição	console.time total menos x-notion-request-timing
Tempo de processamento do servidor	50–2000 ms dependendo do tamanho da consulta	Cabeçalho x-notion-request-timing
Atraso por limitação de taxa	1000–30000 ms por nova tentativa	Código de status HTTP 429 e cabeçalho Retry-After
Tamanho do payload da resposta	10–500 ms por 100 KB	Cabeçalho Content-Length e tempo de download no DevTools

Agora você tem três métodos concretos para perfilhar a latência da API do Notion: temporização no console do lado do cliente, o cabeçalho x-notion-request-timing e gráficos waterfall no DevTools do navegador. Comece executando um teste de linha de base no seu endpoint mais frequente. Se o tempo do servidor for alto, reduza o número de propriedades ou linhas na sua consulta. Se o tempo de rede for alto, mova sua integração para mais perto dos servidores do Notion usando uma função em nuvem em us-east-1 ou eu-west-1. Uma dica avançada: adicione um cabeçalho personalizado X-Request-Id a cada requisição para correlacionar logs entre sua aplicação e o suporte do Notion, caso precise escalar um problema persistente de latência.