La lección 05-01 terminó con un éxito incómodo. Marta encontró el pedido de ocho segundos: 7.402 ms dentro de PostgreSQL, un patrón N+1 con 39 consultas. Pero para llegar ahí necesitó cuatro consultas de Logs Insights, una cronología montada a mano y, sobre todo, que alguien hubiera tenido la precaución de propagar la cabecera X-Peticion-Id por todos los componentes. Si mañana el problema está en la conexión a la base de datos, o en la pasarela de pago, o en un import de la Lambda que tarda dos segundos en arrancar, hay que empezar de cero y adivinar otra vez dónde mirar.

El problema de fondo no es de esfuerzo: es de modelo de datos. Las métricas agregan y pierden el caso individual. Los registros conservan el caso individual pero pierden la relación entre lo que pasó en la tienda y lo que pasó en la Lambda. Ninguno de los dos guarda la estructura de la petición: quién llamó a quién, en qué orden, cuánto tardó cada tramo y cuáles se solapan.

AWS X-Ray guarda exactamente eso. Su unidad de trabajo no es un número ni una línea de texto: es una petición completa, con su árbol de llamadas y su cronología. Del «algo va lento» al «esta llamada concreta tarda 6,2 segundos, y 5,9 de ellos están en una consulta a pedidos».

Esta lección instrumenta la tienda de MercadoFresco, activa el rastreo en la Lambda mercadofresco-estado-pedido y vuelve al pedido de 8,14 segundos para verlo, esta vez, en un solo gráfico.

Aviso de coste. X-Ray cobra por traza registrada y por traza recuperada o escaneada. Es barato si el muestreo está bien configurado y ruinoso si se traza el 100 % de un tráfico alto. Hay una sección entera sobre estrategia de muestreo económica.

1. Por qué las métricas y los registros no bastan
2. El modelo de datos: traza, segmento y subsegmento
3. El identificador de traza y su propagación
4. Muestreo: por qué no se trazan todas las peticiones
5. Reglas de muestreo de MercadoFresco
6. Anotaciones frente a metadatos
7. Una traza completa de un pedido, en un diagrama
8. Permisos que necesita X-Ray
9. Instrumentar la tienda con aws_xray_sdk
10. Subsegmentos manuales y anotaciones útiles
11. El demonio de X-Ray en EC2 y en contenedores
12. Activar el rastreo en mercadofresco-estado-pedido
13. Activar el rastreo en el ALB, en CloudFront y en API Gateway
14. El mapa de servicios: cómo se lee
15. Filtros de traza: el lenguaje de búsqueda
16. Análisis de latencia: histogramas y percentiles
17. El caso guiado: el pedido de 8,14 segundos
18. X-Ray Insights
19. Relación con CloudWatch ServiceLens
20. OpenTelemetry y ADOT: la alternativa abierta
21. Coste y estrategia de muestreo económica
22. Limpieza

La columna que lo cambia todo es «conserva la relación causal». Un registro de la tienda dice llamada a lambda estado-pedido y otro registro, en otro grupo, dice REPORT Duration: 480 ms. Que esos dos eventos pertenezcan a la misma petición es algo que tú tienes que reconstruir. X-Ray lo sabe de nacimiento, porque el identificador viaja con la petición.

Y hay tres preguntas que solo una traza puede responder:

• ¿Cuánto tiempo estuvo la petición esperando frente a trabajando? Un registro con «duración total 8.140 ms» no distingue entre calcular y esperar a otro.
• ¿Qué llamadas se hicieron en paralelo y cuáles en serie? Es la diferencia entre 39 consultas de 190 ms secuenciales (7,4 s) y 39 consultas en paralelo (0,2 s).
• ¿Qué pasó antes del código? El tiempo de arranque en frío de una Lambda, el establecimiento de la conexión TLS, la resolución de DNS. Nada de eso aparece en el log de tu aplicación, porque tu aplicación todavía no se estaba ejecutando.

Tres conceptos y una jerarquía:

• Traza (trace): todo lo que ocurre a raíz de una petición. Se identifica con un ID de traza y agrupa segmentos de todos los servicios implicados.
• Segmento (segment): el trabajo de un servicio o recurso dentro de la traza. La tienda genera un segmento; la Lambda genera el suyo. Contiene nombre, hora de inicio y fin, y estado.
• Subsegmento: un tramo dentro de un segmento. Una consulta SQL, una llamada HTTP a otro servicio, un bloque de cálculo que quieres medir.

Fíjate en el detalle que hace útil este modelo: el segmento de la Lambda (145-685 ms) está contenido en el subsegmento Invoke de la tienda (140-690 ms), y la diferencia de 10 ms es la latencia de red y de la propia API de Lambda. Esa cifra no aparece en ningún log de ninguno de los dos servicios.

Un segmento, en su representación JSON real —simplificada—, se ve así:

Los campos error, fault y throttle marcan el resultado, y su distinción importa porque el mapa de servicios los pinta de colores distintos:

Un ID de traza tiene esta forma:

Que la marca de tiempo esté dentro del identificador no es decorativo: permite a X-Ray localizar la traza sin índice global, y es la razón de que no se puedan consultar trazas de más de 30 días.

La propagación se hace con la cabecera HTTP X-Amzn-Trace-Id:

Tres reglas que hay que interiorizar:

1. El primer componente instrumentado genera el Root. Si el ALB tiene rastreo activo, lo genera él. Si no, lo genera tu aplicación.
2. La decisión de muestreo se toma una sola vez, en el origen, y todos la respetan. Si el Root llega con Sampled=0, la Lambda no enviará su segmento aunque tenga el rastreo activado. Esto evita trazas incompletas y es un comportamiento que confunde mucho al depurar: «he activado X-Ray en la Lambda y no veo nada» suele significar que la decisión de muestreo se tomó aguas arriba.
3. Los SDK propagan la cabecera automáticamente en las llamadas salientes que interceptan. En una llamada que no interceptan —un cliente HTTP exótico, una cola propia— tienes que propagarla tú.

MercadoFresco recibe, en un viernes normal, del orden de 2 millones de peticiones diarias. Trazar todas costaría, a 5 USD por millón de trazas registradas, unos 300 USD al mes solo en registro, sin contar las recuperaciones. Y el 99,9 % de esas trazas serían idénticas y aburridas: peticiones de 80 ms que funcionan.

El muestreo decide qué fracción se traza. Una regla de muestreo tiene dos partes:

• reservoir (depósito): un número fijo de peticiones por segundo que se trazan siempre. Es el suelo: garantiza que siempre tengas ejemplos, incluso con tráfico bajísimo.
• fixed_rate: el porcentaje del resto que se traza. Es el techo proporcional: garantiza representatividad cuando el tráfico sube.

Con reservoir: 1 y fixed_rate: 0.05:

Ese es el diseño: a volumen bajo trazas casi todo (y te cuesta nada); a volumen alto trazas un porcentaje estable (y el coste crece de forma controlada).

Las reglas se evalúan por prioridad, de menor a mayor número, y gana la primera que coincide. Los criterios de coincidencia son: service_name, service_type, host, http_method, url_path, y atributos de la petición.

La estrategia de Marta: trazar poco lo barato y frecuente, trazar mucho lo caro e importante.

Ese /salud merece un cálculo. El ALB comprueba /salud cada 15 segundos contra cada instancia (03-03). Con 4 instancias en el pico: 4 × 4 = 16 peticiones por minuto, 691.200 al mes. Al 5 % serían 34.560 trazas mensuales de una respuesta de 3 ms que dice OK. No aportan absolutamente nada y ensucian los histogramas de latencia con miles de puntos en 3 ms que desplazan los percentiles. Excluirlos es la primera optimización que hay que hacer siempre.

Las reglas se gestionan de forma centralizada: el SDK las descarga cada 10 segundos desde la API de X-Ray. Cambias una regla en la consola y todas las instancias del ASG la aplican en segundos, sin desplegar código. Esto permite algo muy útil: subir el muestreo al 100 % durante un incidente y bajarlo cuando termina.

Es la distinción más práctica de X-Ray y la que decide si podrás encontrar algo o no:

La regla es simple: si vas a buscar por ello, es una anotación; si solo quieres verlo cuando abras la traza, es un metadato.

Y aquí está la ventaja frente a CloudWatch que conviene subrayar. En 05-01 vimos que poner PedidoId como dimensión de métrica costaría 190.000 USD al mes. Como anotación de X-Ray es gratis y además buscable: annotation.pedido_id = "48213". Es exactamente el hueco que las métricas no pueden cubrir.

Las anotaciones de MercadoFresco, elegidas para responder preguntas reales:

Aviso de privacidad. Las anotaciones y los metadatos se almacenan en X-Ray y son visibles para cualquiera con permiso de lectura. Nunca pongas ahí correos, nombres, direcciones, números de tarjeta ni identificadores directos de persona. Por eso MercadoFresco usa cliente_hash, un hash del identificador interno, y no el correo. Si manejas datos personales bajo el RGPD, esta decisión debe revisarla quien lleve el cumplimiento en tu organización.

Un gráfico así —que en la consola de X-Ray se llama vista de cascada y se genera solo— cuenta la historia entera en dos segundos de lectura: hay una barra roja de 7,4 segundos y todo lo demás es irrelevante en comparación. Compáralo con la hoja de cálculo que Marta montó a mano en 05-01.

El rol rol-mercadofresco-tienda necesita poder enviar segmentos y descargar las reglas de muestreo. AWS tiene una política gestionada para esto:

Si prefieres el mínimo privilegio explícito, que es lo que enseñamos en 04-01, el contenido efectivo es este:

Ninguna de esas acciones admite ARN de recurso —X-Ray no tiene recursos por traza—, así que "Resource": "*" es correcto aquí; es el mismo caso que cloudwatch:PutMetricData en 05-01.

Para el rol de la Lambda, rol-lambda-miniaturas y el de mercadofresco-estado-pedido, basta con la política gestionada AWSXRayDaemonWriteAccess, o la aún más específica AWSXRayWriteOnlyAccess.

Y para leer trazas, el grupo de personas que hace guardia necesita:

Instalación:

Y la instrumentación mínima de una aplicación Flask, que es lo que corre en las instancias del ASG:

Cuatro decisiones que hay que entender, porque cada una evita un problema real:

• context_missing="LOG_ERROR" es probablemente el parámetro más importante del fichero. Con el valor por defecto (RUNTIME_ERROR), cualquier código instrumentado que se ejecute fuera de una petición HTTP —una tarea programada, un script de mantenimiento, un hilo de fondo, el publicador de métricas por lotes de 05-01— lanza una excepción y tumba la tarea. Con LOG_ERROR, escribe un error en el log y sigue. La observabilidad no debe tumbar la aplicación, nunca.
• plugins=("EC2Plugin",) hace que cada segmento incluya el instance_id y la zona de disponibilidad. Cuando una sola instancia del ASG esté degradada, esa anotación es la que lo revela. Hay equivalentes ECSPlugin y ElasticBeanstalkPlugin.
• patch_all() incluye psycopg2, el controlador de PostgreSQL. Eso significa que cada consulta a mercadofresco-pedidos genera un subsegmento automáticamente, con el texto de la consulta sanitizado. Es exactamente lo que va a delatar el N+1.
• daemon_address: el SDK no habla con la API de X-Ray. Escribe paquetes UDP a un demonio local, que se encarga de agrupar y enviar. Por eso una llamada instrumentada añade microsegundos, no milisegundos.

Si prefieres instrumentar más finamente, patch() acepta la lista de módulos: patch(("boto3", "psycopg2", "requests")). Evita instrumentar sqlite3 en producción si lo usas para cachés locales de alta frecuencia: generarías miles de subsegmentos inútiles.

La instrumentación automática cubre las llamadas a servicios externos. Los tramos de tu código hay que marcarlos tú:

Y el decorador, para funciones que se llaman desde varios sitios:

El fallo de instrumentación más común en producción. El SDK guarda el segmento actual en una variable de contexto por hilo. Si lanzas un hilo nuevo, ese hilo no tiene contexto y todo lo instrumentado que ejecute fallará o se perderá:

Si esto te parece frágil, tienes razón: lo es. Es uno de los argumentos serios a favor de OpenTelemetry, que resuelve la propagación de contexto de forma más limpia. Lo vemos al final de la lección.

El demonio de X-Ray es un proceso ligero que escucha en el puerto 2000/UDP, agrupa los segmentos que le mandan los SDK y los envía a la API de X-Ray por lotes.

¿Por qué esta arquitectura? Porque desacopla la aplicación de la red. Si la API de X-Ray está lenta o caída, la aplicación no se entera: sigue escribiendo paquetes UDP que, en el peor caso, se pierden. Una traza perdida no es un problema; una tienda bloqueada esperando a la API de trazas, sí.

Instalación en las instancias del ASG, añadida al user data de lt-mercadofresco-tienda:

Notas de campo:

• UDPAddress: 127.0.0.1:2000, no 0.0.0.0. Solo debe escuchar en la interfaz local; nadie de fuera tiene por qué enviarle segmentos.
• TotalBufferSizeMB: si el buffer se llena, el demonio descarta segmentos y lo anota en su log. Ver SegmentsRejectedCount creciendo significa que hay que subirlo o bajar el muestreo.
• No hace falta abrir nada en sg-mercadofresco-tienda: el tráfico es local. La salida hacia la API de X-Ray sale por el NAT (03-01), o mejor aún, por un endpoint de interfaz de VPC para com.amazonaws.eu-west-1.xray si quieres que ni siquiera pase por internet.

En contenedores (módulo 10), el demonio se despliega como un contenedor sidecar en la misma definición de tarea, y la aplicación lo alcanza por localhost en ECS con red awsvpc. Se detalla en 10-01.

En Lambda no hay demonio que instalar: AWS lo ejecuta por ti dentro del entorno de ejecución. Basta una casilla y un permiso.

Los dos modos:

Para mercadofresco-estado-pedido, que la llama la tienda, PassThrough sería suficiente y más barato. Para mercadofresco-generar-miniaturas, que la dispara un evento de S3 y no tiene origen instrumentado, hace falta Active o no se trazará nunca nada.

Con solo eso ya obtienes el segmento con la duración, el arranque en frío y los errores. Para ver dentro de la función, hay que instrumentar igual que en EC2:

El detalle que hace perder tiempo a todo el mundo la primera vez: en Lambda no puedes anotar el segmento raíz. Lo crea y lo controla el entorno de ejecución. xray_recorder.current_segment() existe, pero put_annotation sobre él se ignora silenciosamente. Las anotaciones van siempre en un subsegmento propio.

Otro detalle valioso: el subsegmento Initialization que ves en las trazas de Lambda es el arranque en frío. Si tu p99 de Duration es malo pero el p50 es bueno, mira ese subsegmento: casi siempre es un import pesado que se puede mover dentro del handler o reducir. Es el diagnóstico que en 02-05 solo podíamos intuir.

El ALB genera la cabecera automáticamente y no hay nada que activar: es la razón por la que la tienda de MercadoFresco recibe un Root sin que nadie lo haya programado. Lo que el ALB no hace es generar un segmento propio, así que su tiempo de proceso no aparece como nodo en el mapa. Esa latencia se sigue viendo en la métrica TargetResponseTime de CloudWatch (05-01), y ese es un buen ejemplo de que las dos herramientas se complementan.

Si algún día MercadoFresco pone una API detrás de API Gateway:

CloudFront es la pieza que falta, y conviene ser honesto: CloudFront no participa en las trazas de X-Ray. Su identificador propio es x-amz-cf-id, que aparece en sus registros de acceso. Para correlacionar el tiempo de la CDN con la traza, MercadoFresco registra ese valor como anotación:

Con eso, dada una traza puedes buscar la línea correspondiente en los registros de CloudFront en S3, y al revés. No es tan cómodo como un nodo en el mapa, pero cierra el círculo.

El mapa de servicios es el gráfico que X-Ray construye agregando todas las trazas de la ventana temporal seleccionada. No es un diagrama de arquitectura dibujado por nadie: es lo que realmente pasa, deducido del tráfico.

Cómo se lee, elemento a elemento:

Los tipos de nodo también importan: X-Ray distingue nodos de servicio (algo que tú instrumentas, con su propio segmento) de nodos de recurso descendente (una base de datos, un bucket de S3, que no están instrumentados pero cuyo tiempo se mide desde el llamante). Un nodo de RDS rojo significa que las llamadas a RDS fallan o tardan, no que el servidor de PostgreSQL esté informando de nada.

Tres patrones que se reconocen de un vistazo en un mapa real:

1. Un nodo rojo aislado con todo lo demás verde: el culpable está claro.
2. Todo rojo aguas abajo de un nodo: hay un fallo en cascada; el culpable es el más profundo.
3. Un nodo que aparece de repente y no debería estar ahí: una dependencia que alguien introdujo sin decirlo. Es una de las razones por las que este mapa es útil incluso sin incidentes.

Los grupos permiten tener un mapa filtrado, por ejemplo solo del flujo de compra:

Un grupo con InsightsEnabled genera además métricas propias en CloudWatch, sobre las que se pueden crear alarmas.

Aquí está la potencia real de X-Ray. El lenguaje de expresiones de filtro:

Desde la CLI:

Un script que Marta usa cuando llega una queja concreta, y que sustituye a las cuatro consultas de Logs Insights de 05-01:

La consola de X-Ray ofrece, para cada nodo del mapa y para cada búsqueda, un histograma de latencia en escala logarítmica. Es la herramienta que revela lo que un percentil resume.

Un histograma unimodal —una sola joroba— significa que todas las peticiones se comportan parecido: si es lento, es lento para todos, y el problema es estructural.

Un histograma bimodal —dos jorobas— significa que hay dos poblaciones distintas de peticiones, y ese es el hallazgo más valioso que ofrece X-Ray. El de mercadofresco-tienda en el pico del viernes:

Un p95 de 1,8 s no habría mostrado nada raro. El p99 de 8,2 s sí. Pero lo que de verdad convence es ver que hay dos jorobas separadas: no es una degradación general, es un subconjunto concreto de peticiones que se comporta de otra manera. Y en X-Ray puedes seleccionar la segunda joroba en el histograma con el ratón y ver solo esas trazas. Eso lleva directamente al caso guiado.

Una comparación útil que hay que aprender a hacer, entre dos versiones de la aplicación:

Y el filtro que aísla exactamente el efecto de un despliegue, que es la pregunta que más veces se hace tras publicar una versión:

Volvemos al pedido 48213, esta vez con X-Ray. Compara el esfuerzo con las cuatro consultas de 05-01.

Paso 1. Encontrar la traza. Una sola búsqueda:

Aparece una traza, 8,14 s. En 05-01 esto costó dos consultas de Insights y saber el hash del cliente.

Paso 2. Abrir la vista de cascada. Se ve inmediatamente:

Paso 3. Ver la naturaleza del problema. Al desplegar el subsegmento de la base de datos aparecen 39 subsegmentos consecutivos, cada uno de unos 190 ms, con el mismo SQL sanitizado:

Esto es lo que un log no puede enseñar: la forma. Treinta y nueve barras idénticas, una detrás de otra, sin solaparse. El diagnóstico se lee en el gráfico antes de que nadie lea el SQL. Es el patrón N+1: el código recorre las líneas del pedido y consulta el precio de cada producto por separado.

Paso 4. Confirmar que es sistemático y no un caso aislado. El filtro:

Devuelve 187 trazas en 24 horas. Y el complementario:

Devuelve 2. La lentitud crece con el número de líneas del pedido: confirmado. Esta es exactamente la pregunta que las anotaciones estaban ahí para responder, y por eso num_lineas era una anotación y no un metadato.

Paso 5. Cuantificar el impacto en el negocio. Con el filtro anterior sobre 30 días: 5.610 pedidos afectados, con más de 4 segundos de espera en la confirmación. Son los pedidos más grandes, es decir, los de mayor importe. Ese dato es el que convierte una tarea técnica en una prioridad.

Paso 6. Arreglar. Una sola consulta en lugar de 39:

Paso 7. Verificar con datos, no con impresiones. Se despliega como versión 2.14.4 y se compara:

Fíjate en la última fila, que es un efecto secundario que nadie había previsto: al eliminar el N+1, la presión sobre mercadofresco-pedidos cae a la mitad. La alarma mercadofresco-rds-conexiones-altas de 05-01 deja de estar al borde todos los viernes. Un problema de latencia era también un problema de capacidad.

Y el paso 8, el que cierra el ciclo con 05-01: ahora que sabemos cuál es el problema, se crea una alarma para que no vuelva sin avisar. El grupo grupo-mercadofresco-pedidos con Insights activado publica métricas en CloudWatch, y la métrica TiempoConfirmacionPedido que creamos en 05-01 ya vale para detectar la regresión. X-Ray diagnostica; CloudWatch vigila. Ninguno sustituye al otro.

Insights analiza continuamente las trazas de un grupo, construye una línea base de comportamiento normal y detecta anomalías sin que tú definas umbrales. Cuando encuentra una, abre un «insight» con:

• El momento de inicio y el estado (activo o resuelto).
• La causa raíz probable: el nodo y el tipo de error que más contribuye.
• El impacto: número de peticiones y usuarios afectados.
• Un gráfico de anomalía frente a la línea base.

Con NotificationsEnabled=true, cada insight genera un evento de EventBridge (07-03), que se puede encaminar a alertas-mercadofresco. Ese es el enlace que convierte X-Ray de herramienta de diagnóstico en herramienta de detección.

Dos limitaciones honestas:

• Insights detecta anomalías respecto a lo habitual, no problemas. Si tu servicio siempre ha tardado 8 segundos, nunca lo marcará.
• Necesita volumen. Con poco tráfico muestreado, la línea base es ruidosa y produce falsos positivos. Es una razón más para no muestrear al 1 %.

ServiceLens es la vista de CloudWatch que une las tres señales en una sola pantalla. Es literalmente el mapa de servicios de X-Ray, pero con las métricas de CloudWatch y un acceso directo a los registros correlacionados.

Requisito: X-Ray activo y, para la correlación de registros, que los grupos estén asociados. El flujo de trabajo que ServiceLens habilita, y que es el que Marta acaba usando a diario:

Métrica → mapa → traza → subsegmento → log. Ese es el camino completo, y ahora MercadoFresco lo tiene entero.

Sería deshonesto enseñar X-Ray sin decir que hoy el estándar de la industria es OpenTelemetry (OTel), un proyecto de la CNCF que define una API, un SDK y un protocolo (OTLP) neutrales respecto al proveedor.

AWS Distro for OpenTelemetry (ADOT) es la distribución de AWS de OpenTelemetry, soportada oficialmente, que puede enviar trazas a X-Ray y a cualquier otro destino a la vez.

Qué recomendar, con criterio:

• Proyecto nuevo, o con intención de no atarse a AWS: OpenTelemetry con ADOT. El coste inicial extra —configurar el colector— se paga solo la primera vez que quieras enviar las mismas trazas a otro sitio, o migrar.
• Proyecto existente ya instrumentado con el SDK de X-Ray, todo en AWS: no hay urgencia. Funciona, está soportado y migrar tiene coste.
• Caso de MercadoFresco: Marta ha instrumentado con el SDK de X-Ray porque es lo más rápido de poner en marcha y todo su sistema está en AWS. Ha anotado en el registro de decisiones técnicas que la migración a ADOT es la evolución natural cuando la aplicación crezca o si algún día se plantea multinube. No es deuda técnica oculta: es una decisión consciente con fecha de revisión.

Una nota de compatibilidad que ahorra un mal rato: X-Ray propaga X-Amzn-Trace-Id y OTel propaga traceparent (W3C). Si mezclas ambos en un mismo sistema, hay que configurar el propagador xray en OTel para que las trazas no se rompan en la frontera.

Un ejemplo mínimo de ADOT en Python, para que veas la diferencia de forma:

Fíjate en que no hay una sola línea de código de la aplicación: opentelemetry-instrument envuelve el proceso e instrumenta las librerías conocidas. Eso, para una aplicación grande y existente, es una ventaja enorme.

«Traza recuperada» es cada vez que alguien abre una traza o ejecuta un filtro. Consultar es barato; registrar es lo caro.

Cálculo para MercadoFresco. Tráfico: unos 2 millones de peticiones al día, 60 millones al mes.

Escenario A: sin reglas, muestreo por defecto (1/s + 5 %).

Escenario B: con las reglas de MercadoFresco.

Menos coste que el escenario A y con el 100 % de las confirmaciones de pedido trazadas, que es lo único que de verdad importa. Eso es lo que hace una buena estrategia de muestreo: no traza menos, traza mejor.

Escenario C: el error, muestreo al 100 % de todo.

60 millones de trazas: 300 USD/mes, más el impacto en el rendimiento del demonio y en la usabilidad de la consola, que se llena de trazas de /salud. Nunca lo hagas fuera de una ventana de depuración acotada.

Las cinco reglas de la estrategia económica:

1. Excluir siempre /salud y los estáticos. Es el 57 % del tráfico de MercadoFresco y su valor diagnóstico es cero.
2. Trazar al 100 % las rutas críticas de negocio. Son pocas peticiones y son las que importan.
3. Depósito de al menos 1/s en la regla por defecto, para tener ejemplos incluso de madrugada.
4. Subir el muestreo temporalmente durante un incidente y bajarlo al terminar. Las reglas son centralizadas y se aplican en 10 segundos, sin desplegar.
5. Vigilar el coste con un presupuesto filtrado por servicio = X-Ray (módulo 11).

Y una advertencia de rendimiento, no de coste: cada subsegmento tiene un precio en tamaño. Un segmento no puede pasar de 64 KB, y un patch_all() sobre una aplicación que hace miles de consultas pequeñas por petición genera segmentos enormes que el demonio acaba descartando. Si ves SegmentsRejectedCount en el log del demonio, revisa qué estás instrumentando.

Importante: las trazas ya registradas no se pueden borrar y expiran solas a los 30 días. No hay almacenamiento que siga costando. Lo que sí hay que hacer es quitar la instrumentación del código si no vas a seguir usándola, o al menos dejar context_missing="LOG_ERROR" para que un SDK sin demonio no genere errores en el log.

1. «He activado X-Ray y no veo nada». Por orden de probabilidad: (a) el demonio no está corriendo o no escucha en 2000/UDP; (b) falta xray:PutTraceSegments en el rol; (c) la petición llegó con Sampled=0 y la decisión se respeta aguas abajo; (d) estás mirando la región equivocada.

2. Poner anotaciones en el segmento raíz de una Lambda. Se ignoran en silencio: el segmento raíz lo controla el entorno de ejecución. Las anotaciones van en un subsegmento creado por ti.

3. Dejar context_missing en su valor por defecto. Cualquier código instrumentado fuera de una petición HTTP —tareas programadas, hilos, scripts— lanzará excepciones y tumbará el proceso. Pon siempre LOG_ERROR.

4. Confundir anotación con metadato. Si no puedes filtrar por algo, es que lo pusiste como metadato. Solo las anotaciones están indexadas, y hay un máximo de 50 por traza.

5. Poner datos personales en anotaciones. Correo, nombre, dirección, tarjeta: nunca. Usa un hash. Las trazas las ve todo el que tenga permiso de lectura, y viven 30 días.

6. Trazar el health check. El /salud cada 15 segundos genera decenas de miles de trazas inútiles al mes, ensucia los histogramas y desplaza los percentiles. Es la primera exclusión que hay que crear.

7. Muestrear al 100 % «para no perderse nada». 300 USD al mes en el caso de MercadoFresco, una consola inservible y el demonio descartando segmentos. Trazar mejor no es trazar más.

8. Perder el contexto en hilos. El segmento vive en una variable por hilo. Si lanzas un hilo, tienes que pasarle el segmento explícitamente. Es el fallo más frecuente en aplicaciones con paralelismo.

9. Buscar trazas de hace dos meses. No existen: X-Ray retiene 30 días y punto. Si necesitas análisis histórico, exporta lo que te interese a S3 mientras esté disponible.

10. Esperar que CloudFront aparezca en el mapa. No aparece. Correlaciona con la anotación cf_id y los registros de la CDN en S3.

11. Instrumentar sin propagar en las llamadas propias. Si tu código llama a otro servicio con un cliente HTTP que el SDK no parchea, la cabecera X-Amzn-Trace-Id no viaja y la traza se corta ahí. Se propaga a mano.

12. Usar X-Ray como sustituto de los registros. No lo es. Las trazas están muestreadas: la petición que buscas puede no estar. Los registros lo tienen todo. Se complementan: la traza te dice dónde mirar, el registro te dice qué decía.

Consejo final: la inversión que más rendimiento da en X-Ray no es la instrumentación, sino elegir bien cinco o seis anotaciones. pedido_id, cliente_hash y num_lineas son las que han resuelto este caso. Piensa qué preguntas te van a hacer —«a este cliente le pasa siempre», «empezó con el despliegue del martes», «solo con pedidos grandes»— y anota exactamente lo que hace falta para responderlas con un filtro.

MercadoFresco lanza una API pública para que las tiendas de barrio asociadas consulten stock y creen pedidos al por mayor. Tráfico previsto:

Requisitos: cada pedido y cada factura deben poder investigarse individualmente; hay que poder diagnosticar la latencia de /stock sin arruinarse; el presupuesto de X-Ray es de 25 USD al mes.

Diseña el conjunto completo de reglas de muestreo con prioridades, depósitos y tasas. Calcula el número de trazas mensuales y el coste. Justifica cada regla y di qué anotaciones pondrías en la API.

Esta es la cascada de una traza de 6,45 segundos de POST /api/pedidos/confirmar:

Identifica al menos tres problemas distintos, ordénalos por impacto en milisegundos, propón una solución concreta para cada uno y estima la latencia resultante. Indica además qué anotación o subsegmento añadirías para poder detectar cada uno de estos problemas de forma automática en el futuro.

Un lunes, Sara avisa de que el 3 % de los pedidos de la última semana no han llegado a generar la factura. Los clientes tienen su pedido confirmado y su reparto en marcha, pero no hay factura. No hay errores en CloudWatch, ninguna alarma ha saltado, mercadofresco-estado-pedido no registra Errors, y en X-Ray las trazas de esos pedidos aparecen completas y en verde.

Arquitectura implicada: la tienda confirma el pedido, publica en el tema alertas-mercadofresco, y un proceso de facturación suscrito a ese tema genera el PDF y lo sube a mercadofresco-informes-analitica. Ese proceso de facturación no está instrumentado con X-Ray.

Explica: por qué X-Ray no lo ha detectado, qué le falta a la observabilidad de MercadoFresco, qué combinación de las herramientas de 05-01 y 05-02 usarías para diagnosticarlo, y qué instrumentación y qué alarma dejarías montadas para que la próxima vez se detecte en minutos. Sé concreto con los comandos.

Solución 1

Análisis previo. El tráfico total es de 4.124.960 peticiones/día ≈ 124 millones/mes. Al muestreo por defecto (5 %) serían 6,2 millones de trazas: 30,50 USD. Nos pasamos del presupuesto, y encima gastaríamos casi todo en trazas de /stock idénticas.

Reglas propuestas:

Cálculo detallado de /stock, que es donde está el 97 % del tráfico y donde se decide todo:

• 4.000.000/día ÷ 86.400 s = 46,3 peticiones/segundo.
• Depósito: 1/s × 2.592.000 s/mes = 2.592.000… que ya es demasiado. Cuidado con el depósito cuando el volumen es alto: el depósito es un suelo, no un techo, y con 46 peticiones por segundo siempre hay una que trazar.

Rehacemos: con depósito 1/s el suelo mensual es de 2,59 millones de trazas solo de /stock (12,95 USD). Es demasiado para lo que aporta. Depósito 0 y tasa fija del 0,05 %:

• 124.000.000 × 0,0005 = 62.000 trazas/mes. Suficiente para un histograma de latencia representativo de una ruta que responde en 25 ms.

Tabla corregida:

Coste: (586.000 − 100.000) × 5 / 1.000.000 = 2,43 USD/mes en registro, más recuperaciones dentro de la capa gratuita. Muy por debajo de los 25 USD, y con el 100 % de facturas y pedidos mayoristas trazado.

Con el margen sobrante se puede subir /catalogo al 25 % y activar Insights sobre el grupo de la API.

La lección del ejercicio: el depósito es peligroso en rutas de altísimo volumen, porque garantiza un suelo de una traza por segundo que en un mes son 2,6 millones. Para el tráfico masivo, depósito 0 y tasa muy baja; para el tráfico escaso y valioso, depósito alto y tasa 100 %.

Anotaciones propuestas para la API:

Solución 2

Problema 1 — Arranque en frío de la Lambda: 2.980 ms (46 % del total).

El subsegmento Initialization de casi 3 segundos es un arranque en frío patológico. Lo normal en Python es 200-600 ms; 2.980 ms indica import muy pesados —típicamente pandas, numpy, un SDK completo— o una conexión establecida en el ámbito del módulo.

Soluciones, por orden de coste-beneficio:

• Revisar los import y mover al handler los que solo se usan en algunos caminos.
• Usar boto3.client() a nivel de módulo (eso está bien: se reutiliza entre invocaciones) pero no abrir conexiones a la base de datos ahí.
• Reducir el tamaño del paquete de despliegue; usar capas para las dependencias grandes.
• Si tras eso sigue siendo alto y la latencia importa: concurrencia aprovisionada (02-05), que elimina el arranque en frío a cambio de pagar por capacidad reservada.

Ahorro estimado: de 2.980 a ~400 ms. −2.580 ms.

Problema 2 — El N+1, otra vez: 1.305 ms (20 %).

Catorce SELECT ... FROM productos WHERE id=? en serie, de unos 93 ms cada uno. El mismo patrón del caso guiado, en otra ruta.

Solución: WHERE id = ANY(...) en una sola consulta. Ahorro: de 1.305 a ~100 ms. −1.205 ms.

Nota: 93 ms por un SELECT por clave primaria también es alto. Merece revisar si hay un índice adecuado, si la conexión se está estableciendo en cada consulta (no hay agrupación de conexiones), o si la instancia de RDS está saturada. Un subsegmento conectar_bd separado lo aclararía.

Problema 3 — Configuración cargada en cada petición: 890 ms (14 %).

cargar_configuracion de 890 ms al principio de cada petición es configuración leída de disco, de red o de Parameter Store en caliente. Debería cargarse una vez al arrancar el proceso y guardarse en memoria.

Solución: cargar al inicio del proceso y refrescar cada N minutos en un hilo de fondo. Ahorro: de 890 a ~1 ms. −889 ms.

Problema 4 — Secrets Manager en la ruta crítica: 310 ms (5 %).

GetSecretValue en cada petición. Como vimos en 04-03, el secreto rota cada 30 días: no hay ninguna razón para leerlo en cada compra. Se cachea con un TTL de 5-15 minutos y se reintenta al recibir un error de autenticación.

Ahorro: de 310 a ~0 ms en el 99,9 % de las peticiones. −310 ms.

Problema 5 — La llamada a la Lambda es síncrona y bloqueante.

Los 3.780 ms del Invoke están enteramente en la ruta crítica del cliente. Pero, ¿de verdad hace falta esperar a que se calcule el estado del pedido antes de responder «confirmado»? Casi con seguridad no: es un buen candidato a invocación asíncrona o a una cola (07-01).

Ahorro potencial: los 3.780 ms enteros desaparecen de lo que el cliente percibe.

Resumen ordenado por impacto:

Latencia resultante aplicando 1-4: 6.450 − 4.984 = ~1.470 ms. Aplicando además el 5: ~430 ms. De 6,45 s a menos de medio segundo.

Instrumentación para detectarlo automáticamente en el futuro:

La anotación num_consultas_sql merece un comentario: es una anotación derivada, calculada por la propia aplicación contando las consultas de la petición. Con ella, un filtro annotation.num_consultas_sql > 10 encuentra todos los N+1 del sistema, presentes y futuros, sin saber de antemano dónde están. Es el tipo de anotación que distingue una instrumentación pensada de una copiada.

Solución 3

Por qué X-Ray no lo detectó, y es importante entenderlo bien.

X-Ray traza lo que está instrumentado. El proceso de facturación no lo está, así que para X-Ray no existe. Las trazas de la tienda terminan en SNS Publish con estado 200 —el mensaje sí se publicó correctamente— y todo aparece verde. El fallo está después del último punto instrumentado, y ese es el punto ciego estructural de cualquier sistema de trazas.

Y hay un segundo motivo, más sutil: aunque instrumentaras el facturador, el patrón es asíncrono. La tienda publica y se olvida. La traza de la tienda termina al publicar; la del facturador sería una traza distinta, disparada por el mensaje. X-Ray las relaciona si el SDK propaga la cabecera a través de SNS (lo hace, en los atributos del mensaje), pero la ausencia de una traza no genera ninguna señal. Nadie está contando cuántos mensajes deberían haberse procesado.

Lo que le falta a la observabilidad de MercadoFresco: no tiene ninguna comprobación de que las dos mitades de un proceso asíncrono cuadren. Es el hueco clásico de las arquitecturas basadas en eventos, y se resuelve con reconciliación, no con trazas.

Diagnóstico, paso a paso:

1. Cuantificar y acotar en el tiempo. Consulta directa a la base de datos para saber cuántos y cuándo:

Si los fallos se concentran en unas horas concretas, hay una causa puntual; si están repartidos uniformemente al 3 %, hay un fallo probabilístico —tiempo de espera agotado, condición de carrera, límite de concurrencia—.

2. Comprobar el eslabón de SNS. Las métricas de SNS en CloudWatch dicen si el mensaje salió y si la entrega falló:

Si NumberOfNotificationsFailed es cero, el mensaje llegó al facturador y el problema está dentro de él. Si no es cero, el problema es de entrega y hay que mirar la política de reintentos de SNS (07-02) y si hay cola de mensajes fallidos.

3. Mirar los registros del facturador con Logs Insights. Aquí es donde 05-01 hace el trabajo:

Es decir: pedidos que entraron al facturador pero no llegaron a registrar la línea de finalización. Y la comprobación cruzada definitiva, buscando un pedido concreto sin factura en todos los grupos a la vez:

Si el pedido aparece en la tienda y no aparece nunca en facturación, el mensaje se perdió. Si aparece y se corta a mitad, el proceso murió: memoria, tiempo de espera agotado, excepción no capturada.

Diagnóstico probable —y el más frecuente en este escenario—: el facturador tarda más de lo que permite su tiempo de espera al generar PDF de pedidos grandes, muere, y SNS no reintenta indefinidamente. Sin cola de mensajes fallidos, el mensaje desaparece en silencio. Es un 3 % estable: los pedidos más grandes.

Lo que hay que dejar montado, en cuatro capas:

a) Instrumentar el facturador con X-Ray. Es lo primero y lo más obvio:

Con anotaciones pedido_id y factura_id. A partir de ahí, la traza de un pedido incluye su facturación y el filtro service("mercadofresco-facturacion") { fault } encuentra los fallos.

b) Una cola de mensajes fallidos. Sin ella no hay forma de saber qué se perdió. MercadoFresco ya tiene el patrón montado con mercadofresco-miniaturas-fallidas (02-05); aquí hace falta el equivalente, y con una alarma sobre ApproximateNumberOfMessagesVisible > 0. El patrón completo —colas, reintentos, idempotencia— es la lección 07-05.

c) La métrica de reconciliación, que es la solución de fondo. Un proceso que cada 15 minutos compara pedidos confirmados con facturas emitidas y publica la diferencia:

Y su alarma:

Con --treat-missing-data breaching: si el propio proceso de reconciliación deja de ejecutarse, eso también es un incidente.

d) La regla general que hay que extraer. En un sistema asíncrono, las trazas no detectan lo que no ocurrió. Solo detectan lo que ocurrió mal. Para lo que no ocurrió hace falta una métrica de reconciliación que compare las dos mitades del proceso: pedidos frente a facturas, mensajes enviados frente a procesados, ficheros subidos frente a miniaturas generadas.

Es exactamente el mismo razonamiento que en 05-01 llevó a poner --treat-missing-data breaching en mercadofresco-sin-pedidos: la ausencia de una señal es una señal, pero solo si alguien la está contando.

MercadoFresco ha pasado del «algo va lento» al «esta llamada concreta tarda 6,2 segundos, y 5,9 de ellos están en una consulta». Sabes por qué las métricas y los registros no bastan: las métricas agregan y pierden el caso individual, los registros conservan el caso pero no la relación causal entre lo que pasó en la tienda y lo que pasó en la Lambda. Solo una traza guarda la estructura completa de una petición.

Dominas el modelo: traza, segmento por servicio y subsegmento por tramo, con error (amarillo, 4xx), fault (rojo, 5xx) y throttle (morado). Conoces el ID de traza con su marca de tiempo incrustada —y por qué eso implica los 30 días de retención— y la cabecera X-Amzn-Trace-Id con sus campos Root, Parent y Sampled, con la regla que más despista: la decisión de muestreo se toma una vez en el origen y todos la respetan, así que «he activado X-Ray en la Lambda y no veo nada» casi siempre significa que llegó con Sampled=0.

Sabes configurar el muestreo con su depósito y su tasa fija, y por qué esa combinación traza casi todo cuando hay poco tráfico y un porcentaje estable cuando hay mucho. Has montado las reglas de MercadoFresco: 100 % de /api/pedidos/*, 0 % de /salud y de los estáticos, 5 % por defecto. Y has aprendido que el depósito es traicionero en rutas de altísimo volumen, donde 1/s son 2,6 millones de trazas al mes.

Tienes clara la distinción que decide si encontrarás algo: anotaciones indexadas y filtrables (máximo 50, cardinalidad libre) frente a metadatos que solo se ven al abrir la traza. Y sabes que pedido_id como anotación de X-Ray es gratis y buscable, mientras que como dimensión de métrica en CloudWatch costaría 190.000 USD al mes: es exactamente el hueco que X-Ray cubre. Con la advertencia de privacidad correspondiente: cliente_hash, nunca el correo.

Has instrumentado la tienda con aws_xray_sdk —xray_recorder.configure con context_missing="LOG_ERROR" para que la observabilidad no tumbe nunca la aplicación, patch_all() que instrumenta boto3 y psycopg2 de forma que cada consulta genera su subsegmento, y el EC2Plugin que añade la instancia y la AZ—, has creado subsegmentos manuales con in_subsegment, y sabes que en hilos hay que pasar el contexto a mano. Has desplegado el demonio en las instancias del ASG, entendiendo por qué existe: el SDK escribe UDP local y no espera nunca a la red. Y has activado el rastreo en mercadofresco-estado-pedido con una política y Mode=Active, sabiendo que en Lambda las anotaciones van en un subsegmento porque el segmento raíz es de solo lectura, y que el subsegmento Initialization es el arranque en frío que en 02-05 solo podíamos intuir.

Sabes leer el mapa de servicios —tamaño, colores, nodos de cliente y de recurso, y los tres patrones que se reconocen de un vistazo—, y buscar con el lenguaje de filtros: service(), fault, responsetime > 5, edge(), annotation.pedido_id = "48213". Y sabes leer un histograma bimodal, que es donde de verdad se ven las dos poblaciones de peticiones que un percentil resume en un número.

Y has cerrado el caso que arrastrábamos desde el módulo 4. El pedido 48213: una sola búsqueda por anotación, la cascada, y ahí estaba —39 subsegmentos consecutivos de 190 ms, el 91 % del tiempo total, un N+1—. Confirmado como sistemático con annotation.num_lineas > 25 AND responsetime > 4, cuantificado en 5.610 pedidos afectados en 30 días, corregido con WHERE id = ANY(...), y verificado: p95 de 6,8 s a 0,44 s, y de regalo DatabaseConnections de 185 a 96 en el pico del viernes. Compara eso con las cuatro consultas y la hoja de cálculo de 05-01.

Conoces X-Ray Insights con sus notificaciones vía EventBridge, ServiceLens como la vista que une métrica → mapa → traza → subsegmento → log, y OpenTelemetry con ADOT como el estándar abierto que hoy AWS recomienda para proyectos nuevos, con la decisión de MercadoFresco anotada y con fecha de revisión en lugar de escondida. Y sabes que todo esto cuesta unos 10,60 USD al mes gracias a una estrategia de muestreo que traza mejor, no más, frente a los 300 USD de trazarlo todo.

Queda una pregunta del módulo 4 sin responder, y es la que ni las métricas ni las trazas pueden contestar. CloudWatch sabe lo que la aplicación dice de sí misma. X-Ray sabe por dónde pasó una petición. Ninguno de los dos sabe quién llamó a la API de AWS. Nadie sabe todavía quién descifró la última copia de la base de datos con alias/mercadofresco-datos, ni quién leyó el secreto mercadofresco/produccion/rds/mfadmin, ni desde qué dirección IP, ni si alguna de esas llamadas falló con AccessDenied porque alguien estaba probando puertas.

Ese registro existe, se llama AWS CloudTrail y lleva grabándolo todo desde el primer día sin que nadie lo haya mirado. En la lección 05-03, «AWS CloudTrail», veremos la diferencia esencial entre registrar llamadas a la API y registrar lo que dice tu aplicación, el historial gratuito de 90 días frente a un trail persistente, cómo crear trail-mercadofresco hacia un bucket cifrado con validación de integridad —y por qué ese bucket debe ser imposible de borrar—, la anatomía comentada de un evento real de kms:Decrypt, la diferencia de coste entre eventos de gestión y eventos de datos, y cómo investigar con Athena y SQL quién asumió un rol, quién leyó un secreto y qué llamadas fallaron con AccessDenied.