Observabilidad de APIs: logs estructurados, métricas y trazas distribuidas

Cuando una API falla, el código HTTP no explica toda la historia. La observabilidad combina logs, métricas y trazas para responder qué ocurrió, por qué ocurrió y qué usuarios fueron afectados.

Empieza por preguntas

Define qué quieres detectar: aumento de errores, lentitud, agotamiento de conexiones o fallos de un proveedor externo. Cada pregunta necesita una señal, un umbral y un responsable.

Logs estructurados

Registra JSON con fecha, nivel, ruta, método, estado, duración, request ID y versión del servicio. Nunca guardes contraseñas, tokens, cookies completas ni datos personales innecesarios.

{"level":"info","request_id":"a8f2","route":"/orders","status":200,"duration_ms":84}

Propaga el request ID entre servicios mediante una cabecera controlada para unir todos los eventos de una misma operación.

Métricas

Mide solicitudes, errores, latencia y saturación. Usa histogramas y percentiles para conocer colas de latencia. Evita etiquetas con valores ilimitados como ID de usuario o URL completa porque pueden hacer crecer demasiado el sistema de métricas.

Trazas distribuidas

Una traza representa una operación completa y cada servicio crea un span. Así puedes saber si la demora ocurrió en la base de datos, en una API externa o en tu código. Propaga el contexto sin incluir datos sensibles.

Alertas accionables

Una alerta debe describir el impacto y el primer paso. Es mejor alertar por una proporción elevada de errores durante varios minutos que por cada excepción aislada. Define severidad, horario y procedimiento de respuesta.

Privacidad

Clasifica campos, redacta información sensible, limita accesos y define retención. La observabilidad debe ayudar a operar el sistema sin convertirse en una copia innecesaria de los datos de usuarios.

Plan de implementación

1. Añade request ID.
2. Estandariza logs.
3. Mide tráfico, errores y latencia.
4. Instrumenta rutas críticas.
5. Crea paneles operativos.
6. Simula una alerta y documenta la respuesta.

Fuentes oficiales

• OpenTelemetry
• Introducción a observabilidad
• The Twelve-Factor App

Si quieres conocer otros artículos parecidos a Observabilidad de APIs: logs estructurados, métricas y trazas distribuidas puedes visitar la categoría Blog.