Latencia por jurisdicción: cómo se publica

Una integración pregunta seguido lo mismo: cuánto tarda tal provincia. La respuesta honesta empieza por aclarar qué se mide: bajo la palabra “latencia” conviven dos intervalos distintos y ninguno se comporta como una promesa.

Un entero suelto en un campo llamado latencia invita a leerlo como un compromiso de tiempo de respuesta, y no lo es. Lo que sigue es el contrato con el que exponemos ese dato: una medida por jurisdicción, con su unidad, su ventana, su muestra y el momento en que se calculó.

Dos latencias que no se pueden sumar

La latencia de consulta mide nuestro lado: el intervalo entre que enviamos una solicitud a la fuente y obtenemos una respuesta utilizable, reintentos incluidos. Depende de la red, del portal y también de nuestra propia cola de trabajo.

La latencia de publicación mide al organismo: cuánto pasa entre el hecho o el labrado del acta y el momento en que esa acta aparece consultable. No la controlamos y sólo es observable para actas que vimos aparecer entre dos consultas; cómo se levanta esa serie está en cómo medir cuánto tarda un acta en aparecer. Acá nos ocupa qué forma tiene ese número cuando sale por la API.

Promediarlas produce un número que no responde ninguna de las dos preguntas. Por eso viajan en campos separados, apoyadas en los relojes que ya distinguimos en los tres relojes de una integración.

Dónde vive el dato en la respuesta

La latencia de la consulta que acabás de hacer pertenece al bloque de esa fuente: es un hecho de esa ejecución. El agregado histórico va en otro recurso —el catálogo de jurisdicciones o uno de estado—, porque recalcularlo en cada consulta suma trabajo sin sumar información.

Cada entrada se identifica con el código canónico de la jurisdicción y no con su nombre visible, por los motivos que desarrollan los códigos estables para jurisdicciones.

Una entrada mínima puede tener esta forma:

{
  "jurisdiccion": "codigo-canonico",
  "medida": "latencia_consulta",
  "unidad": "segundos",
  "ventana": "P7D",
  "p50": null,
  "p95": null,
  "muestra": 0,
  "calculadoEn": "2026-08-29T09:00:00-03:00"
}

Los valores vacíos del ejemplo no son un error: la ventana no reunió observaciones suficientes. Un campo vacío con la muestra a la vista es más honesto que una cifra que nadie puede interpretar.

La unidad y el reloj se declaran

Un número sin unidad no es un dato. Las recomendaciones de nombres de métricas de Prometheus van en esa dirección: unidades base —segundos, no milisegundos— y un sufijo en el nombre que declare esa unidad. Por eso el ejemplo publica segundos y aun así lleva un campo de unidad: en una respuesta pública la convención de nombres no alcanza.

Los instantes que delimitan un intervalo se escriben como fecha y hora con desplazamiento respecto de UTC, según RFC 3339. Sin desplazamiento, la diferencia entre dos marcas es una conjetura, y el desfasaje aparece justo en los cambios de hora o cuando un portal informa en hora local. Ese perfil cubre instantes, no duraciones: la forma de la ventana —P7D en el ejemplo— es una decisión del contrato y hay que documentarla aparte.

El esquema, además, se documenta. OpenAPI permite describir tipo, formato y ejemplos de cada campo, declarar cuáles son obligatorios y admitir el tipo nulo donde corresponde. Un campo que a veces se publica vacío se describe así desde el primer día; no aparece nulo por sorpresa en producción.

Un promedio esconde lo que importa

Lo que se registra son mediciones individuales; lo que se publica es una agregación, y esa agregación es una decisión. La especificación del SDK de métricas de OpenTelemetry separa esos dos momentos: el instrumento toma la medición y una vista define cómo se agrega.

Por eso publicamos percentiles con la ventana sobre la que se calcularon y la cantidad de observaciones. Un percentil sin muestra ni período no se compara con nada, ni siquiera consigo mismo la semana siguiente.

Dos reglas evitan cifras engañosas: no se promedian percentiles de ventanas o instancias distintas, porque el resultado no es un percentil de nada; y por debajo de un mínimo de observaciones se publica el vacío y la muestra, no un valor.

Lo que el número no promete

La latencia publicada describe un pasado observado. No es un objetivo de nivel de servicio, no obliga a la jurisdicción —que no participa del contrato— ni anticipa el comportamiento de una fuente recién migrada de portal.

Tampoco es un indicador de disponibilidad: una fuente caída puede fallar rápido y bajar la latencia medida. Estado de la fuente, cobertura y latencia son tres señales distintas y se leen juntas.

Antes de consumir el campo, verificá cuatro cosas:

• cuál de las dos latencias es, según el nombre de la medida;
• qué unidad declara y qué formato tienen sus fechas;
• qué ventana cubre y con cuántas observaciones;
• qué significa el valor vacío en ese contrato.

Con esas cuatro respuestas, el dato te sirve para dimensionar una ventana de procesamiento nocturno o para decidir en qué orden consultás las jurisdicciones de una flota. Sin ellas, es un entero que invita a prometer lo que nadie puede sostener.

Preguntas frecuentes

¿La latencia publicada es un compromiso de tiempo de respuesta?

No. Describe un período ya observado. Sirve para dimensionar una integración y para comparar jurisdicciones entre sí, pero no compromete cuánto va a tardar la próxima consulta ni reemplaza un acuerdo de nivel de servicio.

¿Por qué publicar percentiles y no un promedio?

Porque el promedio mezcla la mayoría rápida con la cola lenta y devuelve un valor que no describe a ninguna de las dos. Las consultas que rompen un proceso por lotes son las de la cola, y un percentil alto las deja ver; el promedio las diluye entre miles de casos rápidos.

¿Qué significa que la latencia de una jurisdicción venga vacía?

Que la ventana no reunió observaciones suficientes para publicar un valor interpretable. No significa que la fuente sea rápida ni que esté caída: para eso están el estado de la fuente y el tamaño de muestra que acompaña a cada entrada.

¿Sirve la latencia de consulta para configurar el timeout del cliente?

Es un punto de partida, no el valor final. El timeout del cliente debe contemplar la cola de la distribución, los reintentos y el hecho de que una consulta aceptada puede seguir trabajando del lado del servidor aunque la conexión se corte.

Notas relacionadas