Kit inicial de observabilidad en producción para el día uno

Qué se rompe primero cuando una app nueva llega a usuarios reales

Lo que falla primero rara vez es toda la app. Normalmente es un paso que de repente se sobrecarga, una consulta que iba bien en pruebas, o una dependencia que comienza a timeoutear. Los usuarios reales aportan variedad real: teléfonos más lentos, redes inestables, entradas extrañas y picos de tráfico en momentos inoportunos.

Cuando alguien dice “está lento”, puede significar cosas muy distintas. La página puede tardar en cargar, las interacciones pueden ir con lag, una llamada a la API puede estar timeouteando, los jobs en background pueden acumularse, o un servicio de terceros puede estar ralentizando todo.

Por eso necesitas señales antes que dashboards. El día uno no necesitas gráficos perfectos para cada endpoint. Necesitas suficientes logs, métricas y trazas para responder una pregunta rápidamente: ¿dónde se fue el tiempo?

También existe el riesgo real de sobreinstrumentar temprano. Demasiados eventos crean ruido, cuestan dinero y pueden incluso ralentizar la app. Peor aún, los equipos dejan de confiar en la telemetría porque parece desordenada e inconsistente.

Un objetivo realista para el día uno es simple: cuando recibas un informe de “está lento”, puedas encontrar el paso lento en menos de 15 minutos. Debes poder decir si el cuello de botella está en el render del cliente, el handler de la API y sus dependencias, la base de datos o cache, o un worker en background o servicio externo.

Ejemplo: un nuevo flujo de checkout se siente lento. Incluso sin una montaña de herramientas, quieres poder decir: “El 95% del tiempo está en llamadas al proveedor de pagos” o “la consulta del carrito está escaneando demasiadas filas”. Si construyes apps rápido con herramientas como Koder.ai, esa línea base del día uno importa aún más, porque la velocidad de entrega solo ayuda si también puedes depurar rápido.

Logs vs métricas vs trazas en lenguaje sencillo

Un buen kit inicial de observabilidad en producción usa tres “vistas” diferentes de la misma app, porque cada una responde a una pregunta distinta.

Los logs cuentan la historia. Te dicen qué pasó para una petición, un usuario o un job en background. Una línea de log puede decir “pago falló para orden 123” o “timeout DB después de 2s”, además de detalles como request ID, user ID y el mensaje de error. Cuando alguien reporta un problema aislado, los logs suelen ser la forma más rápida de confirmar que ocurrió y a quién afectó.

Las métricas son el marcador. Son números que puedes trendear y sobre los que alertas: tasa de peticiones, tasa de errores, percentiles de latencia, CPU, profundidad de colas. Las métricas te dicen si algo es raro o generalizado y si está empeorando. Si la latencia subió para todos a las 10:05, las métricas lo mostrarán.

Las trazas son el mapa. Una traza sigue una sola petición a medida que se mueve por tu sistema (web -> API -> base de datos -> tercero). Muestra dónde se gasta el tiempo, paso a paso. Eso importa porque “está lento” casi nunca es un gran misterio; suele ser un salto lento.

Durante un incidente, un flujo práctico se ve así:

• Usa métricas para confirmar el impacto (cuántos usuarios, qué tan grave, cuándo empezó).
• Usa trazas para encontrar el paso más lento (un cuello de botella sobre el que actuar).
• Usa logs para explicar el cuello de botella (errores específicos, inputs o casos límite).

Una regla simple: si no puedes apuntar a un cuello de botella después de unos minutos, no necesitas más alertas. Necesitas mejores trazas y IDs consistentes que conecten trazas con logs.

Convenciones del día uno que evitan caos después

La mayoría de incidentes de “no lo encontramos” no se deben a datos faltantes. Ocurren porque la misma cosa se registra de forma distinta entre servicios. Unas pocas convenciones compartidas el día uno hacen que logs, métricas y trazas se alineen cuando necesitas respuestas rápido.

Empieza eligiendo un nombre de servicio por unidad desplegable y mantenlo estable. Si “checkout-api” pasa a ser solo “checkout” en la mitad de tus dashboards, pierdes historial y rompes alertas. Haz lo mismo con las etiquetas de entorno. Elige un conjunto pequeño como prod y staging, y úsalo en todas partes.

Después, facilita seguir cada petición. Genera un request ID en el borde (API gateway, servidor web o primer handler) y pásalo por llamadas HTTP, colas de mensajes y jobs en background. Si un ticket de soporte dice “estaba lento a las 10:42”, un único ID te permite extraer los logs y la traza exactos sin adivinar.

Un conjunto de convenciones que funciona bien el día uno:

• Identidad: nombre del servicio, entorno, versión (o SHA de build)
• Correlación: request ID propagado entre servicios y jobs
• Etiquetas clave: route (o handler), method, status code y tenant/org ID si eres multi-tenant
• Operaciones de traza: nombra las operaciones por endpoints y jobs en background (no por nombres aleatorios de funciones)
• Consistencia: un estilo de nombres y una unidad de tiempo para duraciones

Acuerda las unidades de tiempo desde temprano. Elige milisegundos para latencia de API y segundos para jobs largos, y mantente con ello. Unidades mezcladas crean gráficos que parecen bien pero cuentan la historia equivocada.

Un ejemplo concreto: si cada API registra duration_ms, route, status y request_id, entonces un informe como “checkout está lento para el tenant 418” se convierte en un filtro rápido, no en un debate sobre por dónde empezar.

Logging mínimo para añadir el día uno

Si solo haces una cosa en tu kit inicial de observabilidad, haz que los logs sean fáciles de buscar. Eso empieza con logs estructurados (normalmente JSON) y los mismos campos en todos los servicios. Los logs en texto plano están bien para desarrollo local, pero se convierten en ruido cuando tienes tráfico real, reintentos y múltiples instancias.

Una buena regla: registra lo que realmente usarás durante un incidente. La mayoría de equipos necesita responder: ¿qué petición fue esta? ¿quién la hizo? ¿dónde falló? ¿qué tocó? Si una línea de log no ayuda con alguna de esas, probablemente no debería existir.

Para el día uno, mantén un conjunto pequeño y consistente de campos para poder filtrar y unir eventos entre servicios:

• Timestamp, level e identidad del servicio (service name, version, environment)
• Correlación de la petición (request_id, trace_id si lo tienes)
• Quién/dónde (user_id o session_id, route, method)
• Resultado (status code, duration_ms)
• Contexto de despliegue (región/instancia, release o commit)

Cuando ocurre un error, regístralo una vez, con contexto. Incluye un tipo de error (o código), un mensaje corto, un stack trace para errores del servidor y la dependencia upstream involucrada (por ejemplo: postgres, payment provider, cache). Evita repetir el mismo stack trace en cada retry. En su lugar, adjunta el request_id para poder seguir la cadena.

Ejemplo: un usuario reporta que no puede guardar ajustes. Una búsqueda por request_id muestra un 500 en PATCH /settings, luego un timeout downstream a Postgres con duration_ms. No necesitaste payloads completos, solo la ruta, usuario/sesión y el nombre de la dependencia.

La privacidad es parte del logging, no una tarea posterior. No registres contraseñas, tokens, headers de auth, cuerpos completos de petición ni PII sensible. Si necesitas identificar a un usuario, registra un ID estable (o un valor hasheado) en lugar de emails o teléfonos.

Si construyes apps en Koder.ai (React, Go, Flutter), vale la pena incorporar estos campos en cada servicio generado desde el inicio para no terminar “arreglando el logging” durante tu primer incidente.

Métricas mínimas que detectan la mayoría de problemas en producción

Un buen kit inicial de observabilidad empieza con un conjunto pequeño de métricas que responden rápido a una pregunta: ¿el sistema está sano ahora mismo y, si no, dónde duele?

Las señales doradas

La mayoría de problemas en producción aparecen como una de cuatro “señales doradas”: latencia (respuestas lentas), tráfico (cambios de carga), errores (fallos) y saturación (un recurso compartido al máximo). Si puedes ver estas cuatro señales por cada parte importante de tu app, puedes triagear la mayoría de incidentes sin adivinar.

La latencia debe medirse en percentiles, no en promedios. Controla p50, p95 y p99 para ver cuando un pequeño grupo de usuarios lo está pasando mal. Para tráfico, comienza con requests por segundo (o jobs por minuto para workers). Para errores, separa 4xx de 5xx: un aumento de 4xx suele significar cambios en el comportamiento del cliente o validación; un aumento de 5xx apunta a tu app o sus dependencias. La saturación es la señal de “nos estamos quedando sin algo” (CPU, memoria, conexiones DB, backlog de colas).

Checklist de métricas por componente

Un conjunto mínimo que cubre la mayoría de apps:

• HTTP/API: requests por segundo, latencia p50/p95/p99, tasa 4xx, tasa 5xx
• Base de datos: latencia de consultas (al menos p95), uso del pool de conexiones (in-use vs max), timeouts, conteo de consultas lentas
• Workers/colas: profundidad de cola, tiempo de ejecución de jobs p95, reintentos, conteo de dead-letter o jobs fallidos
• Recursos: CPU %, uso de memoria, uso de disco (y I/O si te afecta), reinicios de contenedores
• Salud del deploy: versión actual, tasa de errores tras deploy, loops de reinicio (a menudo la primera señal de un release malo)

Un ejemplo concreto: si los usuarios reportan “está lento” y la latencia p95 de la API sube mientras el tráfico se mantiene plano, revisa saturación. Si el uso del pool DB está al máximo y los timeouts aumentan, encontraste un cuello de botella probable. Si la DB parece bien pero la profundidad de cola crece rápido, el trabajo en background podría estar acaparando recursos compartidos.

Si construyes apps en Koder.ai, trata este checklist como parte de la definición de hecho del día uno. Es más fácil añadir estas métricas cuando la app es pequeña que durante el primer incidente real.

Trazas mínimas que hacen depurable un “está lento”

Si un usuario dice “está lento”, los logs a menudo te dicen qué pasó y las métricas qué tan frecuente es. Las trazas te dicen dónde se fue el tiempo dentro de una petición. Esa línea de tiempo convierte una queja vaga en una solución clara.

Empieza en el servidor. Instrumenta las peticiones entrantes en el borde de tu app (el primer handler que recibe la petición) para que cada petición pueda generar una traza. La trazabilidad del lado cliente puede esperar.

Una traza buena del día uno tiene spans que mapean a las partes que suelen causar lentitud:

• Span del handler de la petición para toda la petición
• Span de llamada a la base de datos por cada query o transacción
• Span de llamada a cache (get/set) cuando usas cache
• Span de llamada HTTP externa para cada dependencia que llamas
• Span de job en background cuando la petición encola trabajo del que dependes

Para que las trazas sean buscables y comparables, captura algunos atributos clave y manténlos consistentes entre servicios.

Para el span de la petición entrante, registra la route (usa una plantilla como /orders/:id, no la URL completa), método HTTP, status code y latencia. Para spans de DB, registra el sistema DB (PostgreSQL, MySQL), tipo de operación (select, update) y el nombre de la tabla si es fácil añadirlo. Para llamadas externas, registra el nombre de la dependencia (payments, email, maps), host destino y estado.

El muestreo importa el día uno, si no los costes y el ruido crecen rápido. Usa una regla simple head-based: traza 100% de los errores y de las peticiones lentas (si tu SDK lo soporta), y muestrea un pequeño porcentaje del tráfico normal (como 1–10%). Empieza más alto con poco tráfico y reduce a medida que sube el uso.

Cómo se ve algo “bueno”: una traza donde puedes leer la historia de arriba a abajo. Ejemplo: GET /checkout tardó 2.4s, la DB gastó 120ms, cache 10ms y una llamada externa de pagos tardó 2.1s con un retry. Ahora sabes que el problema es la dependencia, no tu código. Esto es el núcleo de un kit inicial de observabilidad en producción.

Un flujo de triage simple para reportes de “está lento”

Cuando alguien dice “está lento”, la victoria más rápida es convertir esa sensación vaga en unas pocas preguntas concretas. Este flujo de triage del kit inicial funciona incluso si tu app es completamente nueva.

El triage en 5 pasos

Comienza estrechando el problema y luego sigue la evidencia en orden. No saltes directo a la base de datos.

1. Confirma el alcance. ¿Es un solo usuario, una cuenta cliente, una región o todos? También pregunta: ¿pasa en Wi‑Fi y en datos móviles, y en más de un navegador/dispositivo?
2. Revisa qué cambió primero. ¿Subió el volumen de peticiones, aumentó la tasa de errores o subió la latencia sola? Un pico de tráfico suele causar encolamiento; un aumento de errores suele señalar una dependencia rota.
3. Divide la lentitud por ruta u operación. Mira la latencia p95 por endpoint (o tipo de job) y encuentra al peor. Si solo una ruta está lenta, enfócate ahí. Si todas las rutas están más lentas, piensa en dependencias compartidas o capacidad.
4. Abre una traza para la ruta lenta. Toma una traza de una petición lenta y ordena los spans por duración. La meta es una frase: “La mayor parte del tiempo está en X”.
5. Valida dependencias y decide rollback. Revisa saturación de la DB, queries lentas, tasa de aciertos de cache y tiempos de respuesta de terceros. Si la lentitud empezó justo después de un deploy o cambio de configuración, hacer rollback suele ser la opción más segura.

Después de estabilizar, haz una pequeña mejora: escribe qué pasó y añade una señal que faltó. Por ejemplo, si no supiste si la lentitud fue solo en una región, añade una etiqueta de región a las métricas de latencia. Si viste un span largo de DB sin pista de qué query, añade etiquetas de query con cuidado o un campo “query name”.

Un ejemplo rápido: si la p95 de checkout salta de 400 ms a 3 s y las trazas muestran un span de 2.4 s en una llamada de pago, puedes dejar de discutir el código de la app y enfocarte en el proveedor, los reintentos y los timeouts.

Comprobaciones rápidas que puedes hacer en 5 minutos

Cuando alguien dice “está lento”, puedes perder una hora solo en entender qué quiere decir. Un kit inicial de observabilidad solo es útil si te ayuda a acotar el problema rápido.

Comienza con tres preguntas clarificadoras:

• ¿Quién está afectado (un usuario, un segmento de clientes, todos)?
• ¿Qué acción exacta está lenta (carga de página, búsqueda, checkout, login)?
• ¿Desde cuándo empezó (hace minutos, después de un deploy, desde esta mañana)?

Luego mira algunos números que suelen indicar hacia dónde ir. No busques el dashboard perfecto. Solo quieres señales de “peor de lo normal”.

• Tasa de errores actual (picos a menudo se sienten como lentitud)
• Latencia p95 del endpoint afectado (no el promedio)
• Saturación: CPU, memoria, conexiones DB o profundidad de cola (elige el que más te golpea)

Si la p95 está elevada pero los errores están estables, abre una traza de la ruta más lenta en los últimos 15 minutos. Una sola traza suele mostrar si el tiempo se gasta en la base de datos, en una API externa o esperando locks.

Luego haz una búsqueda de logs. Si tienes un reporte de usuario específico, busca por su request_id (o el correlation ID) y lee la línea de tiempo. Si no, busca el mensaje de error más común en la misma ventana de tiempo y verifica si coincide con la lentitud.

Finalmente, decide si mitigar ahora o investigar más. Si los usuarios están bloqueados y la saturación es alta, una mitigación rápida (escalar, hacer rollback o desactivar una feature no esencial) puede comprar tiempo. Si el impacto es pequeño y el sistema estable, sigue investigando con trazas y logs de queries lentas.

Ejemplo: diagnosticar un checkout lento sin adivinar

Unas horas después de un release, empiezan a llegar tickets de soporte: “El checkout tarda 20 a 30 segundos.” Nadie puede reproducirlo en su laptop, así que empiezan las conjeturas. Aquí es donde tu kit inicial de observabilidad paga dividendos.

Primero, ve a las métricas y confirma el síntoma. La gráfica de latencia p95 para solicitudes HTTP muestra un pico claro, pero solo para POST /checkout. Otras rutas están normales y la tasa de errores está estable. Eso reduce el problema de “todo el sitio está lento” a “un endpoint se volvió más lento tras el release”.

Luego, abre una traza de una petición lenta POST /checkout. La cascada de la traza hace obvio el culpable. Dos resultados comunes:

• El span “PaymentProvider.charge” está tardando 18 segundos, con la mayor parte del tiempo en espera.
• El span “DB: insert order” está lento, mostrando una larga espera antes de que la query responda.

Ahora valida con logs usando el mismo request ID de la traza (o el trace ID si lo guardas en logs). En los logs de esa petición ves advertencias repetidas como “payment timeout reached” o “context deadline exceeded”, además de reintentos añadidos en el nuevo release. Si es el camino de la base de datos, los logs pueden mostrar mensajes de espera por lock o la query lenta registrada por encima de un umbral.

Con las tres señales alineadas, la solución es clara:

• Haz rollback al release anterior para detener el problema.
• Añade un timeout explícito para la llamada de pago (y limita reintentos).
• Añade una métrica para la latencia de la dependencia, por ejemplo p95 de duración del proveedor de pagos y p95 de duración de queries DB.

La clave es que no tuviste que adivinar. Las métricas señalaron el endpoint, las trazas el paso lento y los logs confirmaron el modo de fallo con la petición exacta en mano.

Errores comunes que hacen perder tiempo en incidentes

La mayor parte del tiempo en incidentes se pierde por huecos evitables: los datos están, pero son ruidosos, riesgosos o falta el detalle que necesitas para conectar síntomas con causa. Un kit inicial de observabilidad solo ayuda si sigue siendo usable bajo estrés.

Una trampa común es loggear demasiado, especialmente cuerpos de petición sin filtro. Suena útil hasta que pagas por almacenamiento enorme, las búsquedas se vuelven lentas y capturas contraseñas, tokens o datos personales. Prefiere campos estructurados (route, status code, latency, request_id) y registra solo pequeños fragmentos permitidos explícitamente del input.

Otro agujero de tiempo son métricas que parecen detalladas pero son imposibles de agregar. Etiquetas de alta cardinalidad como IDs completos de usuario, emails o números de pedido pueden explotar la cantidad de series métricas y hacer los dashboards poco fiables. Usa etiquetas más generales (nombre de ruta, método HTTP, clase de status, nombre de dependencia) y deja lo específico para logs.

Errores que bloquean el diagnóstico rápido:

• Mirar solo promedios. Los promedios ocultan el dolor real; revisa p95 y p99 cuando alguien dice “está lento”.
• Trazas sin contexto. Si los spans no tienen nombres de ruta y nombres claros de dependencia, una traza es una imagen sin etiquetas.
• Sin marcador de release. Si no puedes ver cuándo cambió una versión, acabas adivinando si un deploy causó el problema.
• Alertas sin propietario. Cuando una alerta salta y nadie sabe el siguiente paso, se convierte en ruido y termina ignorada.
• Logs no buscables. Logs en texto libre sin claves consistentes convierten cada incidente en un ejercicio manual de grep.

Un ejemplo práctico: si la p95 de checkout sube de 800ms a 4s, quieres responder en minutos: ¿empezó justo después de un deploy? ¿Se pasa el tiempo en tu app o en una dependencia (DB, proveedor de pagos, cache)? Con percentiles, etiqueta de release y trazas con route y nombres de dependencia, puedes llegar rápido. Sin ellos, quemas la ventana del incidente discutiendo suposiciones.

Pasos siguientes: hacerlo repetible para cada app

La ganancia real es la consistencia. Un kit inicial de observabilidad solo ayuda si cada nuevo servicio se entrega con lo mismo, nombrado igual y fácil de encontrar cuando algo falla.

Convierte tus elecciones del día uno en una plantilla corta que tu equipo reutilice. Mantenla pequeña pero específica.

• Genera un request ID para cada petición entrante y llévalo por logs y trazas.
• Registra los pocos eventos que siempre necesitas: inicio/fin de petición, errores (con tipo claro) y peticiones lentas sobre un umbral.
• Controla un puñado de métricas doradas: tráfico, tasa de errores, latencia (p50 y p95) y una señal de saturación (CPU, memoria, pool DB o profundidad de cola).
• Añade trazas básicas para las rutas clave y las dependencias principales (DB y una API externa).
• Adjunta etiquetas de release/version a logs, métricas y trazas para poder responder: “¿esto empezó después del deploy?”

Crea una vista “home” que cualquiera pueda abrir durante un incidente. Una pantalla debería mostrar requests por minuto, tasa de errores, latencia p95 y tu métrica principal de saturación, con filtros por environment y version.

Mantén las alertas mínimas al principio. Dos alertas cubren mucho: un pico de tasa de errores en una ruta clave y un pico de latencia p95 en la misma ruta. Si añades más, asegúrate de que cada una tenga una acción clara.

Finalmente, programa una revisión mensual recurrente. Elimina alertas ruidosas, afina nombres y añade una señal faltante que hubiera ahorrado tiempo en el último incidente.

Para integrar esto en tu proceso de construcción, añade una “puerta de observabilidad” al checklist de release: no desplegar sin request IDs, etiquetas de versión, la vista home y las dos alertas base. Si publicas con Koder.ai, puedes definir estas señales del día uno en modo planificación antes del despliegue, luego iterar con snapshots y rollback cuando necesites ajustar rápido.