Un protocolo reproducible para benchmarks de la API de cuotas de Pinnacle

Protocolo versión 1.0. Usa este método para recopilar e informar mediciones comparables de APIs de cuotas. Es un protocolo de investigación; todavía no hay disponibles resultados medidos del rendimiento de servicios.

La regla central es simple: una respuesta rápida y un precio fresco son observaciones distintas. Mide cada una con un reloj, un denominador y un alcance definidos. Publica solo lo que la instrumentación pueda respaldar.

Define la pregunta antes de recopilar datos

Métrica	Definición operativa	Evidencia requerida
Latencia de ida y vuelta REST	Tiempo monotónico desde el envío hasta la lectura completa del cuerpo de la respuesta	Tiempos de la solicitud, estado, bytes, política de conexión y umbral de tiempo de espera
Cadencia de actualización observada	Tiempo entre cambios distintos observados por el recolector para una selección emparejada	Identidad de la selección, detección de cambios, horas de recepción y método de muestreo
Frescura de la fuente al cliente	Hora de recepción menos una marca de tiempo significativa de actualización de la fuente	Semántica de marca de tiempo verificada, suposiciones sobre relojes y resolución de la marca de tiempo
Recuperación de la conexión	Tiempo desde la interrupción detectada hasta que se restaura el estado utilizable definido	Detección de desconexión, política de reintentos, finalización de la reproducción o del snapshot y comprobaciones de validez del estado

Estas son las definiciones propuestas por esta publicación. Los estándares de transporte describen interfaces, no el rendimiento ni la frescura de datos de un servicio. Semántica HTTP, estándar WebSockets, estándar SSE.

Si no hay una marca de tiempo de la fuente utilizable, informa de que la frescura no es medible con los campos disponibles. No la sustituyas por la latencia de la solicitud ni por el inicio programado de un evento. Una antigüedad del tablero informada por el servicio puede registrarse bajo esa etiqueta, pero no puede ascenderse a frescura por precio medida de forma independiente.

Congela un manifiesto de la ejecución

Registra la versión de la metodología, el commit del recolector, el servicio, el plan, los derechos de la cuenta, el endpoint, el alcance de la consulta, la región, el entorno del host, el runtime, la concurrencia y la política de reutilización de conexiones. Especifica el tratamiento de DNS y TLS, la compresión de la respuesta, la duración del calentamiento, las horas de inicio y fin medidas, el recuento objetivo de muestras y las condiciones de parada de la recopilación.

Registra también el presupuesto de solicitudes autorizado, la política de reintentos, los tiempos de espera, la política de reconexión y si los datos en bruto pueden conservarse o publicarse. Guarda la evidencia de autorización en un registro privado de revisión; los manifiestos públicos deberían contener una referencia y el estado del permiso, sin credenciales ni datos personales.

Declara previamente el calendario de muestreo y la selección de mercados. Un endpoint cómodo y exitoso no debería sustituir a una carga de trabajo completa de varios deportes. Un plan de pago de alta capacidad no debería compararse con una prueba restringida sin identificar esa diferencia de forma destacada.

Haz explícita la equivalencia de las cargas de trabajo

Empareja el deporte, el evento, la fuente de la casa de apuestas, el periodo, la regla de liquidación, el mercado, la línea, la selección y el estado en vivo/prepartido. Informa por separado de los recuentos de correspondencias no resueltas. Una respuesta de agregador que contiene muchas casas de apuestas es una carga distinta de un snapshot de fuente única; identifica el alcance en lugar de tratar los dos tiempos de solicitud como intercambiables.

Ejecuta cargas de trabajo comparables desde la misma región durante periodos superpuestos cuando esté autorizado. Alterna o aleatoriza el orden de las solicitudes para no favorecer siempre a la primera en un mercado cambiante. Asegúrate de que el propio recolector no esté saturado. Si las cargas de trabajo no pueden hacerse equivalentes, presenta estudios de caso separados en lugar de un ganador universal.

Registra los relojes y las observaciones ausentes

Usa un reloj monotónico para las duraciones transcurridas y marcas de tiempo de reloj de pared con zona horaria para la procedencia de la ejecución. Registra el método de sincronización del reloj y la incertidumbre estimada. Las marcas de tiempo RFC 3339 proporcionan una representación, no una garantía de sincronización. RFC 3339.

Para la frescura, documenta la resolución y la semántica del reloj de la fuente. El desfase de relojes puede producir una antigüedad aparente negativa; márcala como un problema de calidad de datos. No la fuerces a cero ni la descartes en silencio. Si la incertidumbre es comparable a la diferencia informada, la comparación no puede sostener esa precisión.

Persiste los intentos programados, las respuestas correctas, las respuestas fallidas, los tiempos de espera, las cargas inválidas, las solicitudes limitadas, los campos ausentes y los mercados sin emparejar. Un tiempo de espera es una observación fallida o censurada con un plazo conocido, no una latencia inventada en ese plazo. Informa de su recuento y su umbral.

Resume una distribución con honestidad

Informa del recuento de muestras, el periodo de observación, la tasa de éxito, la mediana y los percentiles de cola relevantes. Indica el método de percentil; el protocolo 1.0 usa el rango más cercano: para observaciones ordenadas y un percentil p, selecciona el rango de base uno ceil(p × n), acotado al intervalo de 1 a n.

Los percentiles de latencia deberían identificar su denominador, como las solicitudes validadas correctas. Pon la tasa de fallos junto a ellos para que un subconjunto de éxitos rápidos no oculte los fallos. No publiques un p99 obtenido de un puñado de solicitudes como una característica estable del servicio. Describe la agrupación temporal y las limitaciones de cobertura en lugar de dar a entender que todas las muestras son independientes.

Para el comportamiento de reconexión, define cuándo vuelve a ser utilizable el estado. Que el socket se abra no basta si al tablero local todavía le faltan actualizaciones. Separa la recuperación del transporte de la recuperación del estado de los datos y explica cualquier hueco de reproducción.

Valida los conjuntos de datos antes de publicar

Cada conjunto de datos debe llevar unidades, marcas de tiempo de ejecución y observación, versión del método, fuente/procedencia y permiso para publicar. Valida duraciones finitas no negativas, formatos de marca de tiempo válidos, identidades de servicio y ejecución consistentes, unidades declaradas y los campos obligatorios específicos de cada métrica. Conserva los valores ausentes como ausentes.

Los importadores deberían rechazar unidades inconsistentes o un conjunto de datos etiquetado erróneamente como medido cuando contiene fixtures sintéticos. Los fixtures de prueba pertenecen a un directorio aparte y no pueden alimentar gráficos de investigación de producción, clasificaciones, datos estructurados ni estadísticas agregadas.

Antes de publicar resultados, exige un manifiesto completo, evidencia subyacente permitida, cálculos reproducibles, exclusiones explicadas, revisión editorial y un límite declarado de lo que establece el experimento.

Qué incluir con los resultados

Cada informe debería identificar el alcance de la cuenta autorizada y los límites de solicitudes, confirmar los derechos de publicación, enlazar el método de medición y explicar cómo se verificaron los cálculos de forma independiente. Da a los lectores contexto suficiente para reproducir el trabajo y entender dónde se aplican sus conclusiones.

Lee la guía de transportes para los compromisos de implementación y la guía de normalización para la identidad comparable de mercados. Ninguna sustituye a un conjunto de datos medido.