Observabilidad de una integración: qué medir

Una integración que consulta infracciones no falla de una sola manera. Puede contestar rápido con menos fuentes de las esperadas, contestar tarde y completa, o devolver un 200 que arrastra una jurisdicción caída. Un panel de solicitudes por minuto y errores 5xx no separa ninguno de esos casos.

Medir no es recolectar todo. Es elegir el conjunto mínimo de señales que permite decidir algo: reprocesar un lote, avisarle a un cliente que su reporte va a salir incompleto, frenar un despliegue. Conviene ordenar el trabajo al revés: primero las preguntas operativas, después los instrumentos.

Cuatro preguntas antes de armar un panel

Casi todo lo que un equipo necesita saber entra en cuatro preguntas: ¿la respuesta llegó?, ¿llegó completa?, ¿llegó a tiempo?, ¿el dato es reciente? Cada una tiene su familia de señales y ninguna reemplaza a las otras:

• resultado: cómo terminó la consulta, en el vocabulario del contrato;
• cobertura: cuántas fuentes de las esperadas se pudieron consultar;
• latencia: cuánto tardó, expresada como distribución;
• frescura: qué antigüedad tiene el dato más nuevo que la respuesta contiene.

El resultado no es el código de estado

Un 200 significa que la solicitud HTTP se procesó, no que la consulta de negocio esté completa. Cuando el contrato distingue estados terminales, la métrica de resultado debería usar ese vocabulario y no el del transporte. Contar 2xx contra 5xx esconde el caso más caro: la respuesta exitosa que trae una jurisdicción sin datos.

Con los errores pasa algo parecido: agruparlos por el texto del mensaje produce series que se parten cuando alguien corrige una redacción. RFC 9457 pide que el consumidor use la URI de type como identificador principal del tipo de problema, y reserva detail para la explicación humana de cada ocurrencia. La agrupación se hace por type, no por detail.

Conviene separar al menos cuatro clases: error del cliente, indisponibilidad de una fuente, vencimiento de tiempo y límite de ritmo alcanzado. Un 429 no es una consulta fallida: contarlo como falla infla la tasa de error cuando el sistema funciona como fue diseñado. El matiz está en rate limits interpretables.

Cobertura y frescura, las señales propias de este dominio

Una API de infracciones agrega fuentes heterogéneas. La señal que casi nunca trae un tablero genérico es cuántas de las esperadas contestaron y cuáles fallaron. Sin ese número, un resultado vacío es indistinguible de uno incompleto. Cómo comunicarla lo tratamos en cobertura de una API; acá importa que exista como métrica y no sólo como texto en un log.

La frescura es la otra: la distancia entre el momento en que un organismo publicó el dato y aquel en que la integración lo observó. Se mide por fuente, porque el rezago de un portal no dice nada del resto: una fuente que dejó de actualizarse puede seguir respondiendo 200 durante días.

La latencia: qué instrumento, en qué unidad y desde dónde

Un promedio no describe a una población partida entre consultas rápidas y consultas que esperan a un portal lento. El instrumento tiene que conservar la forma: la especificación del SDK de métricas de OpenTelemetry prevé agregaciones de histograma y vistas para elegir la agregación y acotar qué atributos se reportan.

La unidad es parte de la decisión. Las recomendaciones de nombres de Prometheus piden unidades base —segundos, bytes, no milisegundos ni megabytes— y un sufijo en el nombre que declare esa unidad. Un tablero que mezcla milisegundos y segundos produce alertas mal calibradas.

Queda elegir dónde se toma el tiempo. Abierta por etapa —encolado, consulta a cada fuente, normalización y entrega—, una consulta de cuarenta segundos con treinta y ocho en cola se corrige de otra forma que un organismo lento.

Y hace falta un segundo punto de medición en el consumidor: el servidor no ve su cola, sus reintentos ni cuánto tarda en observar un estado terminal. Con webhooks, entregado y procesado son dos mediciones distintas, y la brecha entre ambas avisa antes que cualquier alarma de infraestructura.

Correlacionar sin acumular datos consultables

Para pasar de la métrica al caso hace falta un identificador que atraviese etapas y servicios. La recomendación W3C Trace Context define los encabezados traceparent y tracestate para propagar ese contexto entre sistemas y reconstruir una consulta que tocó cuatro fuentes.

La correlación no habilita arrastrar el dato consultado. La patente, el CUIT y el DNI no van en etiquetas, nombres de métricas ni URLs: ese criterio está en trazas y métricas sin identificadores sensibles.

Antes de dar por buena una instrumentación, revisá que el vocabulario de resultados y errores esté documentado; que las latencias se publiquen como distribución y en unidades base; que la cobertura por fuente se lea sin abrir un log; y que ninguna etiqueta contenga un identificador consultable.

Una integración bien instrumentada no es la que tiene más gráficos. Es la que, ante un reclamo concreto —“el reporte del martes salió sin una provincia”—, permite contestar en minutos qué pasó y desde cuándo.

Preguntas frecuentes

¿Alcanza con medir latencia y tasa de error?

En una consulta que depende de varias fuentes, no. Una respuesta puede ser rápida y correcta en términos de HTTP y aun así traer menos jurisdicciones de las esperadas. Hace falta una señal de cobertura además de latencia y errores.

¿Por qué agrupar los errores por `type` y no por el mensaje?

Porque el texto legible se reescribe sin aviso y eso rompe las series históricas. RFC 9457 establece que el consumidor debe usar la URI de `type` como identificador principal del tipo de problema; `detail` queda como explicación humana específica de cada ocurrencia.

¿El promedio de latencia sirve para algo?

Sirve para poco cuando conviven dos poblaciones, las consultas rápidas y las que esperan a un portal lento. Una agregación de histograma permite leer percentiles y ver la cola larga; el promedio la disimula.

¿Hace falta medir del lado del cliente si ya medimos en el servidor?

Sí. El servidor no ve la cola del consumidor ni sus reintentos. En una integración asincrónica, el número que le importa al negocio va desde que se aceptó el trabajo hasta que el consumidor observó un estado terminal.

Notas relacionadas