La observabilidad de las API es la capacidad de entender por qué su API se comporta de la manera en que lo hace, examinando la telemetría que emite: métricas, registros (logs) y trazas. Va más allá de observar un conjunto fijo de paneles. Una API bien instrumentada le permite hacer nuevas preguntas sobre su estado interno, incluidas aquellas que nunca anticipó, utilizando solo los datos que ya produce.
Qué significa realmente la observabilidad de las API
El término proviene de la teoría de control, donde un sistema es observable si se puede inferir su estado interno a partir de sus salidas externas. Aplicado al software, una API es observable cuando sus salidas (telemetría) le brindan suficiente información para diagnosticar cualquier comportamiento sin tener que implementar nuevo código para agregar una línea de registro.
Esa última parte importa. Con la observabilidad, cuando un cliente informa de solicitudes de pago lentas a las 2 a.m. para usuarios en una región y con una versión de API específica, debería poder responder "por qué" a partir de los datos que ya recopila. Se instrumenta lo suficientemente bien como para investigar modos de fallo que no predijo. Ese es un objetivo diferente al de las comprobaciones de disponibilidad, que solo responden a preguntas que ya sabía que debía hacer.
Observabilidad vs. Monitorización
La gente usa estas palabras indistintamente, pero describen cosas diferentes.
La monitorización observa señales conocidas y alerta cuando estas cruzan un umbral. Usted decide de antemano qué rastrear (tasa de errores, CPU, latencia p99) y qué se considera negativo. La monitorización responde "¿se está rompiendo lo que esperaba que se rompiera?".
La observabilidad es una propiedad del sistema: cuán bien su telemetría le permite hacer preguntas arbitrarias sobre el estado interno. Responde "¿por qué se está comportando de esta manera?" incluso cuando "esto" es algo para lo que nunca construyó un panel.
En pocas palabras, la monitorización le dice que algo anda mal. La observabilidad le ayuda a descubrir por qué. Necesita ambos. La monitorización le da la alerta; la observabilidad le proporciona el camino desde la alerta hasta la causa raíz. Si desea un tratamiento más profundo sobre el aspecto de las alertas, nuestra guía de monitorización de API lo cubre en detalle.
Aquí está la distinción en una tabla.
| Aspecto | Monitorización | Observabilidad |
|---|---|---|
| Pregunta respondida | ¿Está una señal conocida fuera de rango? | ¿Por qué el sistema se comporta de esta manera? |
| Definido cuándo | Con antelación (comprobaciones predefinidas) | En el momento de la investigación (consultas ad hoc) |
| Mejor para | Modos de fallo conocidos, incumplimientos de SLO | Problemas nuevos e inesperados |
| Salida | Alertas, paneles de estado | Telemetría de alta cardinalidad y consultable |
Los Tres Pilares: Métricas, Registros (Logs), Trazas
La observabilidad se basa en tres tipos de telemetría, a menudo llamados los tres pilares. OpenTelemetry, el estándar neutral del proveedor, los formaliza como "señales" de telemetría. OpenTelemetry actualmente soporta trazas, métricas, registros (logs) y `baggage` (contexto), con eventos y perfiles en desarrollo. Los tres clásicos se corresponden con sus tres primeras señales.
Métricas
Las métricas son mediciones numéricas agregadas a lo largo del tiempo. Para una API, las más importantes son la tasa de solicitudes, la tasa de errores y la distribución de latencia. Informe la latencia como percentiles (p95 y p99), no solo promedios. Un promedio oculta la "cola lenta" que experimentan los usuarios reales.
Las métricas son económicas de almacenar y rápidas de consultar, lo que las hace ideales para paneles y alertas. Su debilidad es la baja cardinalidad: le dicen que la latencia p99 se disparó, pero no qué solicitudes lo causaron.
Registros (Logs)
Los registros (logs) son entradas de eventos discretos con marca de tiempo. Los registros estructurados, emitidos como JSON con campos consistentes, son mucho más útiles que las líneas de texto libre porque se pueden filtrar y agregar.
{
"timestamp": "2026-06-22T02:14:09Z",
"level": "error",
"method": "POST",
"path": "/v2/checkout",
"status": 503,
"duration_ms": 4812,
"trace_id": "8f3a1c9d2e7b4a16",
"user_region": "ap-southeast-1",
"api_version": "2026-05"
}
Observe el campo `trace_id`. Esa ID es lo que vincula una línea de registro con el flujo de solicitud más amplio, lo que nos lleva al tercer pilar.
Trazas
Una traza distribuida sigue una solicitud a medida que viaja a través de los servicios. Cada salto se convierte en un `span` (tramo), y los `spans` comparten una ID de traza para que pueda reconstruir la ruta completa y ver dónde se consumió el tiempo. Cuando una solicitud pasa por un `gateway`, un servicio de autenticación y tres microservicios, la traza muestra qué salto añadió los 4 segundos.
Las trazas son lo que hace que la depuración de microservicios sea manejable. Sin ellas, estaría adivinando qué servicio en la cadena es lento.
Los tres pilares trabajan juntos. Una alerta de métrica señala el pico. Una traza apunta al servicio lento. Los registros de ese servicio, filtrados por ID de traza, le dicen exactamente lo que sucedió.
El Método RED y las Señales Doradas
No necesita rastrear todo. El método RED le ofrece un punto de partida enfocado para cualquier servicio basado en solicitudes. Tom Wilkie lo introdujo en 2015 mientras estaba en Weaveworks, derivado de las cuatro señales doradas de Google.
RED significa:
- Tasa: solicitudes por segundo que su API maneja.
- Errores: el número o la tasa de solicitudes fallidas, como respuestas 5xx y respuestas 4xx inesperadas.
- Duración: la distribución de latencias de solicitud, reportada como p95 y p99.
Rate = requests/sec
Errors = % of 5xx (and unexpected 4xx) responses
Duration = latency distribution, report p95 and p99 (not just average)
RED está centrado en las solicitudes, lo que se adapta bien a las API, `gateways` y mallas de servicios. Su contraparte, USE (Utilización, Saturación, Errores), se dirige a recursos de infraestructura como la CPU y el disco. Para una API, comience con RED y añada USE para los hosts subyacentes.
SLIs y SLOs: Convirtiendo Señales en Objetivos
Los datos de observabilidad se vuelven accionables cuando se les asignan objetivos. El libro SRE de Google define dos términos aquí.
Un indicador de nivel de servicio (SLI) es una medida cuantitativa de un aspecto de su servicio. Los SLI comunes son la latencia de solicitud, la tasa de errores (la fracción de todas las solicitudes que fallan) y el rendimiento en solicitudes por segundo. Estos se alinean limpiamente con RED.
Un objetivo de nivel de servicio (SLO) es un valor o rango objetivo para un SLI. Por ejemplo: "El 99.9 por ciento de las solicitudes en una ventana de 28 días se completan en menos de 300 ms". El SLO le dice a usted y a su equipo cuándo la API está lo suficientemente saludable, y cuándo dedicar tiempo de ingeniería a la fiabilidad en lugar de a las características.
Los SLI y los SLO dan significado a sus métricas. Sin ellos, un gráfico de latencia es solo una línea ondulada; con ellos, es un contrato contra el que puede medir.
Las Herramientas: OpenTelemetry y Backends
Las herramientas de observabilidad se pueden dividir en dos capas: cómo se genera la telemetría y a dónde se envía.
Para la generación, OpenTelemetry es el estándar que vale la pena aprender. Es un proyecto de la Cloud Native Computing Foundation (CNCF), formado por la fusión de OpenTracing y OpenCensus. Es agnóstico a proveedores y herramientas, por lo que funciona con una amplia gama de `backends`. Su principio fundamental es que usted es dueño de los datos que genera, sin dependencia de un proveedor. Proporciona API, SDK de lenguaje, convenciones semánticas, el protocolo `wire` OTLP, auto-instrumentación y el OpenTelemetry Collector.
Para el almacenamiento y análisis, tiene opciones. Prometheus combinado con Grafana es una pila de código abierto común para métricas y paneles. Plataformas comerciales como Datadog y Honeycomb ingieren trazas, métricas y registros y ofrecen consultas de alta cardinalidad. Si utiliza Datadog, nuestra guía de la API de Datadog muestra cómo enviar y extraer datos programáticamente.
El objetivo de OpenTelemetry es que usted instrumente una vez y luego cambie de `backend` sin tener que volver a instrumentar. Esa portabilidad es la principal razón para adoptarlo temprano.
Dónde encajan las pruebas y las comprobaciones sintéticas
La observabilidad no es solo una preocupación de producción. Algunas de las señales más útiles provienen de pruebas que se ejecutan a propósito, tanto antes como después del despliegue.
Desplazamiento a la izquierda: pruebas de contrato y ejecuciones de CI
Antes de que el código se implemente, las pruebas de contrato verifican que su API aún coincida con su especificación. Ejecutarlas en CI detecta cambios que pueden romper el sistema antes de que lleguen a los usuarios. Cada ejecución de prueba de CI es una señal: un aprobado o un fallo vinculado a un `commit`, un entorno y una marca de tiempo. Ese historial es información de observabilidad sobre la calidad de su lanzamiento.
La CLI de Apidog ejecuta sus escenarios de prueba en un `pipeline`. Está construida sobre Node.js y requiere Node v16 o posterior.
npm install -g apidog-cli
# verify the install
node -v && apidog -v
Ejecute un escenario de prueba contra un entorno. La bandera de entorno es obligatoria y debe pasar su `token` explícitamente.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli
Aquí, `-t` es la ID del escenario de prueba, `-e` es la ID del entorno y `-r` establece los formatos del informe (`cli`, `html`, `json`, `junit`). El reportero predeterminado es `cli`. Para ejecutar el escenario desde un archivo CSV o JSON, agregue `-d ./data.csv` (la bandera `-d`, o `--iteration-data`, toma una ruta de archivo). También puede enviar un resumen del informe a la nube de Apidog.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli --upload-report
Para un `pipeline` completo que pueda copiar y adaptar, consulte nuestra guía de Apidog CLI para CI/CD, o la referencia completa de la CLI para cada bandera.
Monitorización sintética en producción
La monitorización sintética ejecuta solicitudes `scripted` contra su API en vivo según un horario, desde el exterior, de la misma manera que lo haría un usuario. Detecta problemas antes de que el tráfico real lo haga y le proporciona un flujo constante de puntos de datos de latencia y disponibilidad. Una comprobación básica de salud de la API es la forma más sencilla. La monitorización sintética completa la extiende a flujos de varios pasos como el inicio de sesión y luego el pago.
Estas comprobaciones son señales de observabilidad por derecho propio. Una ejecución sintética fallida a las 02:00 con una duración de 4 segundos es exactamente el tipo de evento que desea alimentar sus trazas y registros. Para una descripción general de herramientas dedicadas, consulte nuestro resumen de herramientas de pruebas sintéticas, y para plataformas de monitorización de producción, nuestra lista de herramientas de monitorización de API.
Generando Señales Reales con Tareas Programadas de Apidog
Apidog puede producir señales sintéticas recurrentes a través de Tareas Programadas. La característica ejecuta automáticamente escenarios de prueba configurados en momentos determinados, captura los resultados y soporta pruebas de regresión programadas. La encuentra bajo el módulo de Pruebas, en Tareas Programadas.
Algunas cosas a saber antes de depender de ella. Las Tareas Programadas están actualmente en Beta, así que trátelas como una característica en evolución en lugar de una característica estable desde hace mucho tiempo. También requiere un `Runner` autoalojado configurado; las opciones "Se ejecuta en" listan un `Runner` autoalojado hoy, con Apidog Cloud listado como "próximamente". Así que todavía no hay una comprobación programada totalmente alojada en la nube.
Cuando configure una, elige:
- Escenarios de Prueba: uno o más escenarios para ejecutar.
- Modo de Ejecución: un ciclo de tiempo, como cada domingo a las 11 PM o cada 6 horas.
- Notificación: alertas después de cada ejecución, o solo en caso de fallo.
El número de ejecuciones depende de su plan de suscripción. Para una implementación práctica, consulte nuestra guía de Tareas Programadas de Apidog.
El valor aquí es cerrar el ciclo. Usted diseña y prueba su API en un solo lugar, luego ejecuta esos mismos escenarios con una cadencia para que sigan generando señales de éxito/fallo y latencia sobre las que pueda actuar. Pruebe Apidog gratis, no se requiere tarjeta de crédito, y convierta sus escenarios de prueba existentes en señales recurrentes.
Un Camino Práctico hacia una API Observable
Si está empezando de cero, trabaje en este orden:
- Emita registros estructurados con un esquema consistente y una ID de traza en cada solicitud.
- Instrumente con OpenTelemetry para que las trazas, métricas y registros compartan contexto y se mantengan portátiles entre los `backends`.
- Rastree las métricas RED (tasa, errores, duración con p95 y p99) y colóquelas en un panel.
- Defina SLI y SLO para que sus métricas tengan objetivos, no solo tendencias.
- Agregue pruebas de contrato en CI para detectar cambios que pueden romper el sistema antes del lanzamiento.
- Ejecute comprobaciones sintéticas programadas contra producción, por ejemplo, con Tareas Programadas de Apidog.
No tiene que hacer los seis pasos a la vez. Incluso el primer paso, los registros estructurados con ID de traza, le ayudará a avanzar mucho más allá de los registros de texto plano.
Preguntas Frecuentes
¿Qué es la observabilidad de las API?
La observabilidad de las API es la capacidad de entender el estado interno de una API a partir de la telemetría que emite, es decir, métricas, registros (logs) y trazas. Una API observable le permite investigar por qué se comporta de cierta manera, incluyendo problemas que no anticipó, sin agregar nueva instrumentación primero.
Observabilidad de las API vs monitorización: ¿cuál es la diferencia?
La monitorización observa señales predefinidas y alerta cuando cruzan un umbral, respondiendo "¿se está rompiendo algo que esperaba que se rompiera?". La observabilidad es una propiedad del sistema que le permite hacer preguntas nuevas y arbitrarias sobre su comportamiento, respondiendo "¿por qué está sucediendo esto?". La monitorización le dice que algo anda mal; la observabilidad le ayuda a encontrar la causa. Necesita ambos.
¿Cuáles son los tres pilares de la observabilidad?
Los tres pilares son métricas, registros (logs) y trazas. Las métricas son números agregados como la tasa de solicitudes y los percentiles de latencia. Los registros son entradas con marca de tiempo de eventos discretos, idealmente estructurados como JSON. Las trazas siguen una solicitud a través de los servicios para que pueda ver dónde se consumió el tiempo. OpenTelemetry formaliza esto como señales de telemetría.
¿Cómo se hace observable una API?
Comience emitiendo registros estructurados con una ID de traza en cada solicitud. Instrumente su código con OpenTelemetry para que las métricas, registros y trazas compartan contexto. Rastree las métricas RED, defina SLI y SLO como objetivos, agregue pruebas de contrato en CI y ejecute comprobaciones sintéticas programadas contra producción. Cada paso añade una señal consultable.
¿Es OpenTelemetry un requisito para la observabilidad?
No. La observabilidad es una propiedad que puede lograr con cualquier herramienta de telemetría, y muchos equipos usaron agentes propietarios mucho antes de que existiera OpenTelemetry. Dicho esto, OpenTelemetry es el estándar CNCF neutral del proveedor, por lo que adoptarlo le permite instrumentar una vez y cambiar de `backends` como Prometheus, Datadog o Honeycomb sin tener que volver a instrumentar. Es una opción predeterminada sólida, no un requisito.