Um protocolo reproduzível para benchmarks da API de odds da Pinnacle

Protocolo versão 1.0. Use este método para coletar e informar medições comparáveis de APIs de odds. Este é um protocolo de pesquisa; resultados medidos de desempenho de serviços ainda não estão disponíveis.

A regra central é simples: uma resposta rápida e um preço fresco são observações diferentes. Meça cada uma com relógio, denominador e escopo definidos. Publique apenas o que a instrumentação consegue sustentar.

Defina a pergunta antes de coletar dados

Métrica	Definição operacional	Evidência necessária
Latência de ida e volta REST	Tempo monotônico do envio até a leitura completa do corpo da resposta	Tempo da requisição, status, bytes, política de conexão e limiar de timeout
Cadência observada de atualizações	Tempo entre mudanças distintas observadas pelo coletor para uma seleção correspondida	Identidade da seleção, detecção de mudança, horários de recebimento e método de amostragem
Frescor da fonte até o cliente	Horário de recebimento menos um timestamp significativo de atualização da fonte	Semântica de timestamp verificada, premissas de relógio e resolução do timestamp
Recuperação da conexão	Tempo desde a interrupção detectada até a restauração do estado utilizável definido	Detecção de desconexão, política de novas tentativas, conclusão do replay ou do snapshot e verificações de validade do estado

Estas são as definições propostas por esta publicação. Os padrões de transporte descrevem interfaces, não o desempenho nem o frescor de dados de um serviço. Semântica HTTP, padrão WebSockets, padrão SSE.

Se não houver um timestamp da fonte utilizável, informe que o frescor não é mensurável com os campos disponíveis. Não o substitua pela latência da requisição nem pelo início agendado de um evento. Uma idade de painel informada pelo serviço pode ser registrada sob esse rótulo, mas não pode ser promovida a frescor por preço medido de forma independente.

Congele um manifesto da execução

Registre a versão da metodologia, o commit do coletor, o serviço, o plano, os direitos da conta, o endpoint, o escopo da consulta, a região, o ambiente do host, o runtime, a concorrência e a política de reutilização de conexões. Especifique o tratamento de DNS e TLS, a compressão da resposta, a duração do aquecimento, os horários de início e fim medidos, a contagem-alvo de amostras e as condições de parada da coleta.

Registre também o orçamento de requisições autorizado, a política de novas tentativas, os timeouts, a política de reconexão e se os dados brutos podem ser retidos ou publicados. Guarde a evidência de autorização em um registro privado de revisão; manifestos públicos devem conter uma referência e o status da permissão, sem credenciais nem dados pessoais.

Declare previamente o cronograma de amostragem e a seleção de mercados. Um endpoint conveniente e bem-sucedido não deve substituir uma carga de trabalho completa de vários esportes. Um plano pago de alta capacidade não deve ser comparado com um teste restrito sem identificar essa diferença com destaque.

Torne explícita a equivalência das cargas de trabalho

Faça a correspondência de esporte, evento, fonte da casa de apostas, período, regra de liquidação, mercado, linha, seleção e estado ao vivo/pré-jogo. Informe separadamente as contagens de mapeamentos não resolvidos. Uma resposta de agregador contendo muitas casas de apostas é um payload diferente de um snapshot de fonte única; identifique o escopo em vez de tratar os dois tempos de requisição como intercambiáveis.

Execute cargas de trabalho comparáveis a partir da mesma região durante períodos sobrepostos, quando autorizado. Alterne ou randomize a ordem das requisições para evitar favorecer sempre a primeira requisição em um mercado em mudança. Garanta que o próprio coletor não esteja saturado. Se as cargas de trabalho não puderem ser tornadas equivalentes, apresente estudos de caso separados em vez de um vencedor universal.

Registre relógios e observações ausentes

Use um relógio monotônico para durações decorridas e timestamps de relógio de parede com fuso horário para a proveniência da execução. Registre o método de sincronização do relógio e a incerteza estimada. Timestamps RFC 3339 fornecem uma representação, não uma garantia de sincronização. RFC 3339.

Para o frescor, documente a resolução e a semântica do relógio da fonte. O desvio de relógio pode produzir uma idade aparente negativa; sinalize isso como um problema de qualidade de dados. Não a limite a zero nem a descarte silenciosamente. Se a incerteza for comparável à diferença informada, a comparação não sustenta essa precisão.

Persista tentativas agendadas, respostas bem-sucedidas, respostas com falha, timeouts, payloads inválidos, requisições limitadas, campos ausentes e mercados sem correspondência. Um timeout é uma observação com falha ou censurada com um prazo conhecido, não uma latência inventada nesse prazo. Informe sua contagem e seu limiar.

Resuma uma distribuição com honestidade

Informe a contagem de amostras, o período de observação, a taxa de sucesso, a mediana e os percentis de cauda relevantes. Declare o método de percentil; o protocolo 1.0 usa o nearest rank: para observações ordenadas e percentil p, selecione a posição de base um ceil(p × n), limitada ao intervalo de 1 a n.

Os percentis de latência devem identificar seu denominador, como requisições validadas bem-sucedidas. Coloque a taxa de falha ao lado deles para que um subconjunto de sucessos rápidos não esconda as falhas. Não publique um p99 a partir de um punhado de requisições como uma característica estável do serviço. Descreva o agrupamento temporal e as limitações de cobertura em vez de sugerir que todas as amostras são independentes.

Para o comportamento de reconexão, defina quando o estado volta a ser utilizável. A abertura do socket não basta se o painel local ainda estiver sem atualizações. Separe a recuperação do transporte da recuperação do estado dos dados e explique quaisquer lacunas de replay.

Valide os conjuntos de dados antes da publicação

Cada conjunto de dados deve carregar unidades, timestamps de execução e observação, versão do método, fonte/proveniência e permissão para publicar. Valide durações finitas não negativas, formatos de timestamp válidos, identidades consistentes de serviço e execução, unidades declaradas e os campos obrigatórios específicos de cada métrica. Preserve valores ausentes como ausentes.

Os importadores devem rejeitar unidades inconsistentes ou um conjunto de dados rotulado indevidamente como medido quando contém fixtures sintéticos. Fixtures de teste pertencem a um diretório separado e não podem alimentar gráficos de pesquisa de produção, rankings, dados estruturados ou estatísticas agregadas.

Antes de publicar resultados, exija um manifesto completo, evidência subjacente permitida, cálculos reproduzíveis, exclusões explicadas, revisão editorial e um limite declarado do que o experimento estabelece.

O que incluir com os resultados

Todo relatório deve identificar o escopo da conta autorizada e os limites de requisições, confirmar os direitos de publicação, vincular o método de medição e explicar como os cálculos foram verificados de forma independente. Dê aos leitores contexto suficiente para reproduzir o trabalho e entender onde suas conclusões se aplicam.

Leia o guia de transportes para os compromissos de implementação e o guia de normalização para a identidade comparável de mercados. Nenhum dos dois substitui um conjunto de dados medido.