DEV Community

Cover image for Observabilidad de API: Qué es y cómo lograrla
Roobia
Roobia

Posted on • Originally published at apidog.com

Observabilidad de API: Qué es y cómo lograrla

La observabilidad de las API es la capacidad de entender por qué una API se comporta de cierta manera a partir de la telemetría que ya emite: métricas, registros (logs) y trazas. En la práctica, significa instrumentar la API para diagnosticar latencia, errores, degradaciones por región, cambios de versión y fallos entre servicios sin tener que desplegar código nuevo solo para añadir más logs.

Prueba Apidog hoy

Qué significa realmente la observabilidad de las API

El término proviene de la teoría de control: un sistema es observable si se puede inferir su estado interno a partir de sus salidas externas. En software, una API es observable cuando sus salidas de telemetría permiten diagnosticar su comportamiento interno sin añadir instrumentación después del incidente.

Ejemplo práctico: un cliente reporta que las solicitudes de pago están lentas a las 02:00, solo para usuarios de una región y una versión concreta de la API. Una API observable debería permitirle responder:

  • qué endpoints fueron afectados;
  • qué versión de API participó;
  • qué región o segmento de usuarios sufrió el problema;
  • qué servicio interno añadió la latencia;
  • qué errores aparecen en los logs relacionados;
  • qué despliegue, dependencia o cambio coincide con el incidente.

La diferencia clave es que no se trata solo de tener paneles. Se trata de poder hacer preguntas nuevas sobre datos que ya existen.

Observabilidad vs. monitorización

Monitorización y observabilidad se complementan, pero no son lo mismo.

La monitorización observa señales conocidas y alerta cuando cruzan un umbral. Por ejemplo:

  • tasa de errores mayor al 1%;
  • latencia p99 superior a 500 ms;
  • CPU por encima del 85%;
  • endpoint /checkout devolviendo demasiados 5xx.

La observabilidad permite investigar por qué ocurre el problema, incluso si no había un panel específico preparado para ese caso.

En resumen:

  • La monitorización le dice que algo va mal.
  • La observabilidad le ayuda a encontrar la causa raíz.

Si necesita profundizar en alertas y comprobaciones, consulte la guía de monitorización de API.

Aspecto Monitorización Observabilidad
Pregunta respondida ¿Está una señal conocida fuera de rango? ¿Por qué el sistema se comporta así?
Definido cuándo Antes del incidente Durante la investigación
Mejor para Fallos conocidos, incumplimientos de SLO Problemas nuevos o inesperados
Salida Alertas y paneles Telemetría consultable de alta cardinalidad

Los tres pilares: métricas, registros y trazas

La observabilidad se apoya en tres tipos principales de telemetría:

  1. métricas;
  2. registros;
  3. trazas.

OpenTelemetry los formaliza como señales de telemetría. Actualmente soporta trazas, métricas, registros y baggage como contexto, con eventos y perfiles en desarrollo.

1. Métricas

Las métricas son mediciones numéricas agregadas en el tiempo. Para una API, empiece por estas:

  • solicitudes por segundo;
  • tasa de errores;
  • latencia p50, p95 y p99;
  • throughput por endpoint;
  • errores por versión de API;
  • errores por región o entorno.

Evite depender solo del promedio de latencia. El promedio puede ocultar la cola lenta que sí afecta a usuarios reales.

Por ejemplo:

GET /v1/users
p50 latency: 80 ms
p95 latency: 240 ms
p99 latency: 900 ms
error rate: 0.2%
Enter fullscreen mode Exit fullscreen mode

Las métricas son baratas de almacenar y rápidas de consultar. Son ideales para dashboards y alertas. Su limitación es que suelen tener menos detalle que los logs o las trazas.

2. Registros logs

Los registros son eventos discretos con marca de tiempo. Para que sean útiles en producción, emítalos como datos estructurados, no como texto libre.

Ejemplo de log JSON para una solicitud de API:

{
  "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"
}
Enter fullscreen mode Exit fullscreen mode

Campos recomendados para logs de API:

timestamp
level
method
path
status
duration_ms
trace_id
request_id
user_region
api_version
environment
service_name
Enter fullscreen mode Exit fullscreen mode

El campo más importante para correlación es trace_id. Permite conectar un log concreto con la traza completa de la solicitud.

3. Trazas

Una traza distribuida sigue una solicitud mientras atraviesa varios servicios. Cada salto se representa como un span.

Por ejemplo, una solicitud de pago puede pasar por:

API Gateway
  -> Auth Service
  -> Checkout Service
  -> Payment Service
  -> Inventory Service
  -> Notification Service
Enter fullscreen mode Exit fullscreen mode

Una traza permite ver cuánto tiempo consumió cada parte:

POST /v2/checkout                4812 ms
├─ API Gateway                    30 ms
├─ Auth Service                   45 ms
├─ Checkout Service              120 ms
├─ Payment Service              4300 ms
├─ Inventory Service             180 ms
└─ Notification Service           70 ms
Enter fullscreen mode Exit fullscreen mode

Sin trazas, probablemente investigaría servicio por servicio. Con trazas, puede ver rápidamente qué dependencia agregó la mayor latencia.

Los tres pilares funcionan mejor juntos:

  1. una métrica dispara la alerta;
  2. una traza identifica el servicio lento;
  3. los logs filtrados por trace_id explican qué ocurrió.

El método RED y las señales doradas

No necesita medir todo desde el primer día. Para APIs, empiece con el método RED:

  • Rate: solicitudes por segundo.
  • Errors: solicitudes fallidas.
  • Duration: distribución de latencia. 
Rate     = requests/sec
Errors   = % de respuestas 5xx y 4xx inesperadas
Duration = latencia p95 y p99, no solo promedio
Enter fullscreen mode Exit fullscreen mode

RED encaja bien con APIs, gateways y servicios HTTP. Para infraestructura, compleméntelo con USE:

  • utilización;
  • saturación;
  • errores.

Una configuración inicial razonable para una API sería:

Dashboard principal:
- requests/sec por endpoint
- error rate por endpoint
- p95 latency por endpoint
- p99 latency por endpoint
- 5xx por versión de API
- 4xx inesperados por cliente
Enter fullscreen mode Exit fullscreen mode

SLIs y SLOs: convertir señales en objetivos

Las métricas se vuelven accionables cuando tienen objetivos.

Un SLI es un indicador cuantitativo de la calidad del servicio. Ejemplos:

latencia de solicitudes
tasa de errores
disponibilidad
throughput
Enter fullscreen mode Exit fullscreen mode

Un SLO es el objetivo esperado para ese indicador.

Ejemplos:

El 99.9% de las solicitudes deben completarse en menos de 300 ms en una ventana de 28 días.

El 99.95% de las solicitudes a /v2/checkout deben devolver una respuesta no 5xx en una ventana de 7 días.

El endpoint /health debe estar disponible el 99.99% del tiempo.
Enter fullscreen mode Exit fullscreen mode

Sin SLO, una gráfica de latencia es solo una línea. Con SLO, puede decidir si debe priorizar fiabilidad o nuevas funcionalidades.

Herramientas: OpenTelemetry y backends

Divida la pila de observabilidad en dos capas:

  1. generación de telemetría;
  2. almacenamiento, consulta y visualización.

Para generar telemetría, OpenTelemetry es el estándar más práctico. Es un proyecto de la Cloud Native Computing Foundation CNCF, nacido de la fusión de OpenTracing y OpenCensus.

OpenTelemetry proporciona:

  • APIs y SDKs por lenguaje;
  • auto-instrumentación;
  • convenciones semánticas;
  • protocolo OTLP;
  • OpenTelemetry Collector;
  • soporte para métricas, registros y trazas.

La ventaja principal es la portabilidad: instrumenta una vez y puede enviar los datos a diferentes backends.

Para almacenamiento y análisis, puede usar:

  • Prometheus y Grafana para métricas y dashboards;
  • Datadog para métricas, logs y trazas;
  • Honeycomb para consultas de alta cardinalidad;
  • otros backends compatibles con OpenTelemetry.

Si utiliza Datadog, la guía de la API de Datadog muestra cómo enviar y extraer datos programáticamente.

Dónde encajan las pruebas y las comprobaciones sintéticas

La observabilidad no empieza solo en producción. Las pruebas también generan señales útiles.

Hay dos puntos especialmente importantes:

  1. pruebas de contrato en CI;
  2. comprobaciones sintéticas en producción.

Desplazamiento a la izquierda: pruebas de contrato y CI

Antes del despliegue, las pruebas de contrato validan que la API sigue cumpliendo su especificación. Si se ejecutan en CI, detectan cambios incompatibles antes de que lleguen a usuarios.

Cada ejecución de CI produce datos observables:

commit
branch
environment
test scenario
status
duration
timestamp
report
Enter fullscreen mode Exit fullscreen mode

La CLI de Apidog permite ejecutar escenarios de prueba dentro de un pipeline. Está construida sobre Node.js y requiere Node v16 o posterior.

Instalación:

npm install -g apidog-cli

# verificar instalación
node -v && apidog -v
Enter fullscreen mode Exit fullscreen mode

Ejecutar un escenario de prueba contra un entorno:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli
Enter fullscreen mode Exit fullscreen mode

Dónde:

-t = ID del escenario de prueba
-e = ID del entorno
-r = formatos de reporte: cli, html, json, junit
Enter fullscreen mode Exit fullscreen mode

Para ejecutar el escenario con datos desde CSV o JSON:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  -d ./data.csv \
  -r html,cli
Enter fullscreen mode Exit fullscreen mode

Para subir 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
Enter fullscreen mode Exit fullscreen mode

Para un pipeline completo, consulte la guía de Apidog CLI para CI/CD o la referencia completa de la CLI.

Monitorización sintética en producción

La monitorización sintética ejecuta solicitudes programadas contra la API real, desde fuera del sistema, como lo haría un usuario.

Sirve para detectar:

  • caídas antes de que las reporten los usuarios;
  • degradación de latencia;
  • errores en flujos críticos;
  • problemas de autenticación;
  • fallos en dependencias externas.

Una comprobación básica de salud de la API puede validar disponibilidad. La monitorización sintética amplía esto a flujos de varios pasos, como iniciar sesión y completar un pago.

Ejemplo de flujo sintético:

1. POST /auth/login
2. GET /users/me
3. POST /cart/items
4. POST /checkout
5. GET /orders/{id}
Enter fullscreen mode Exit fullscreen mode

Cada ejecución sintética debería producir al menos:

status
duration_ms
endpoint
environment
timestamp
region
error_message
trace_id, si está disponible
Enter fullscreen mode Exit fullscreen mode

Para revisar opciones dedicadas, consulte el resumen de herramientas de pruebas sintéticas y la lista de herramientas de monitorización de API.

Generar señales reales con Tareas Programadas de Apidog

Apidog puede generar señales sintéticas recurrentes mediante Tareas Programadas. Esta función ejecuta automáticamente escenarios de prueba configurados, captura resultados y permite programar pruebas de regresión.

Puede encontrarla en:

Pruebas -> Tareas Programadas
Enter fullscreen mode Exit fullscreen mode

Al crear una tarea, configure:

  • Escenarios de prueba: uno o más escenarios que se ejecutarán.
  • Modo de ejecución: por ejemplo, cada 6 horas o cada domingo a las 23:00.
  • Notificación: después de cada ejecución o solo cuando falle.

Puntos importantes:

  • Tareas Programadas está actualmente en Beta.
  • Requiere un Runner autoalojado configurado.
  • Apidog Cloud aparece como opción futura, pero no como comprobación programada completamente alojada actualmente.
  • El número de ejecuciones depende del plan de suscripción.

Para una implementación paso a paso, consulte la guía de Tareas Programadas de Apidog.

El valor práctico es reutilizar los escenarios que ya diseñó para convertirlos en señales recurrentes de éxito, fallo y latencia.

Camino práctico hacia una API observable

Si parte de cero, implemente la observabilidad en este orden.

1. Estandarice logs estructurados

Emita JSON con campos consistentes:

{
  "timestamp": "2026-06-22T02:14:09Z",
  "level": "info",
  "service": "checkout-api",
  "method": "POST",
  "path": "/v2/checkout",
  "status": 200,
  "duration_ms": 143,
  "trace_id": "8f3a1c9d2e7b4a16",
  "environment": "production"
}
Enter fullscreen mode Exit fullscreen mode

2. Propague un identificador de traza

Asegúrese de que cada solicitud tenga un trace_id y que ese ID aparezca en:

  • logs;
  • spans;
  • errores;
  • respuestas internas;
  • eventos de pruebas sintéticas, si aplica.

3. Instrumente con OpenTelemetry

Use OpenTelemetry para que métricas, logs y trazas compartan contexto y puedan enviarse a diferentes backends.

4. Mida RED por endpoint

Empiece por:

requests/sec
error rate
p95 latency
p99 latency
Enter fullscreen mode Exit fullscreen mode

Agrupe por:

endpoint
method
status_code
api_version
environment
region
Enter fullscreen mode Exit fullscreen mode

5. Defina SLIs y SLOs

Ejemplo:

SLI: porcentaje de solicitudes POST /v2/checkout con status no 5xx y duración < 300 ms

SLO: 99.9% durante una ventana de 28 días
Enter fullscreen mode Exit fullscreen mode

6. Añada pruebas de contrato en CI

Ejecute escenarios de prueba en cada pull request o antes del despliegue.

7. Ejecute comprobaciones sintéticas

Programe flujos críticos contra producción:

login
consulta de perfil
creación de recurso
checkout
consulta de estado
Enter fullscreen mode Exit fullscreen mode

No necesita implementar todo en una sola iteración. Solo pasar de logs de texto plano a logs estructurados con trace_id ya mejora mucho la capacidad de diagnóstico.

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: métricas, registros y trazas. Una API observable permite investigar por qué se comporta de cierta manera sin añadir instrumentación nueva antes de poder diagnosticar.

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. La observabilidad permite hacer preguntas nuevas sobre el comportamiento del sistema. La monitorización indica que algo está mal; la observabilidad ayuda a encontrar la causa.

¿Cuáles son los tres pilares de la observabilidad?

Los tres pilares son métricas, registros y trazas. Las métricas muestran valores agregados como tasa de solicitudes y latencia. Los registros describen eventos concretos. Las trazas muestran el recorrido de una solicitud a través de servicios.

¿Cómo se hace observable una API?

Empiece con logs estructurados y trace_id en cada solicitud. Después, instrumente con OpenTelemetry, mida RED, defina SLI y SLO, añada pruebas de contrato en CI y ejecute comprobaciones sintéticas programadas contra producción.

¿Es OpenTelemetry obligatorio para tener observabilidad?

No. La observabilidad es una propiedad del sistema, no una herramienta concreta. Sin embargo, OpenTelemetry es una opción sólida porque es neutral respecto al proveedor, está respaldado por CNCF y permite enviar la misma instrumentación a backends como Prometheus, Datadog o Honeycomb.

Top comments (0)