Práctica: Instrumentar trazas a mano (spans, eventos, errores, enlaces, muestreo)

Lo que vas a aprender en este TP

• Crear spans con el SDK
• Señalar errores, eventos y enlaces
• Consultar con TraceQL y muestrear

Introducción #

Lo que vas a aprender en esta sección

• Crear spans con el SDK
• Señalar errores, eventos y enlaces
• Consultar con TraceQL y muestrear

Contexto. El servicio de pedidos no tiene ninguna biblioteca auto-instrumentada para su lógica de negocio. Lo instrumentas a mano para ver las etapas de un pedido, sus errores de pago y sus procesos por lotes.

Requisitos previos: Docker y Python 3.10 o superior; la pila grafana/otel-lgtm (Collector, Tempo, Loki, Prometheus, Pyroscope y Grafana en un solo contenedor)  ·  Duración estimada: 50 min

Trazas ricas y consultables, y un muestreo controlado.

Puesta en práctica #

Pasos guiados, con su corrección.

1. 1. Arrancar la pila de observabilidad

   ¿Por qué? Una sola imagen proporciona un Collector OTLP y todos los backends: nos centramos en la señal.

   Lanza grafana/otel-lgtm, crea un entorno Python y apunta los exportadores al puerto OTLP/HTTP 4318.

2. 2. Inicializar el SDK

   ¿Por qué? El TracerProvider lleva el recurso y el exportador; el BatchSpanProcessor envía por lotes.

   Instala el SDK y el exportador OTLP/HTTP y escribe otel_setup.py, que configura el recurso (service.name, service.version, deployment.environment.name) y la exportación.

3. 3. Crear una traza de negocio

   ¿Por qué? Spans con el nombre de cada etapa, con SpanKind y atributos conformes a las convenciones, hacen la traza legible por todas las herramientas.

   Escribe commande.py: un span raíz traiter commande y tres hijos (stock como CLIENT con atributos de base de datos, cálculo, pago), un evento y un error de pago una vez de cada tres con record_exception y estado ERROR.

4. 4. Explorar y consultar con TraceQL

   ¿Por qué? TraceQL filtra por la estructura y los atributos de los spans: una consulta encuentra las trazas importantes.

   En Grafana, abre Explore > Tempo. Ejecuta las consultas siguientes, abre una traza con error y encuentra el evento y la excepción del span payer.

5. 5. Vincular un proceso por lotes con enlaces

   ¿Por qué? Un lote que procesa elementos de varias trazas no puede tener varios padres: se usan enlaces.

   Escribe lot.py: tres trazas «recepción» independientes y luego un span facturer lot enlazado a las tres. Encuentra los enlaces en el detalle del span.

6. 6. Muestrear

   ¿Por qué? El muestreo por ratio reduce el volumen; parentbased garantiza que una traza se conserve o se descarte entera.

   Vuelve a lanzar commande.py con un muestreo del 20 % y compara el número de trazas recibidas; comprueba que ninguna traza está incompleta. Explica por qué el tail sampling del Collector sería preferible para conservar todos los errores.

Nivel de dificultad : ●●●○○ (3/5)