Observabilidad y OpenTelemetry
En esta página
Actualizado el 2 de noviembre de 2026 según el SDK
mistralai3.7.0: los métodos de traza se encuentran bajoclient.workflows.executions; sus versiones asíncronas llevan el sufijo_async(esperar la versión síncrona falla),execution_idse pasa como argumento clave, y las respuestas exponenotel_trace_data,span_treeyevents(los camposspans,activity_countoerror_countleídos por la versión anterior ya no existen);traceparentse pasa como parámetro de ejecución, ya que la cabecera HTTP está obsoleta. Fuentes: Observabilidad de flujos de trabajo · client-python.
Por qué observar tus flujos de trabajo
Un flujo de trabajo en producción puede encadenar decenas de actividades, llamar a múltiples servicios externos y ejecutarse desde unos pocos segundos hasta varios días. Sin observabilidad, diagnosticar un problema es como buscar una aguja en un pajar: sabes que la ejecución falló, pero no en qué paso, tras cuántos intentos, ni si el culpable es tu código o una API de terceros. La plataforma Workflows de Mistral integra OpenTelemetry de forma nativa para responder a esta pregunta: cada actividad, cada error y cada duración se registra como un span en una traza distribuida, sin necesidad de instrumentación por tu parte.
Dos conceptos estructuran este modelo. La traza representa todo el recorrido de una ejecución, desde el desencadenante inicial hasta el resultado final. El span, por su parte, es una operación individual dentro de esa traza: cada actividad genera uno automáticamente, portando su nombre, horas de inicio y fin, duración de la ejecución, estado (éxito o error) y cualquier atributo personalizado. Estos spans forman una jerarquía: el span del flujo de trabajo es el padre, y los spans de las actividades son sus hijos, lo que reproduce la estructura completa de la ejecución.
Nombra las actividades para facilitar la lectura
El parámetro name del decorador de actividad determina la etiqueta que aparece en las trazas. Es una inversión de diez segundos al escribir que te ahorrará mucho tiempo durante un incidente.
import mistralai.workflows as workflows
@workflows.activity(name="Extract source text")
async def extraire_texte(url: str) -> dict:
async with httpx.AsyncClient() as client:
response = await client.get(url)
return {"texte": response.text}
@workflows.activity(name="Mistral sentiment analysis")
async def analyser_sentiment(texte: str) -> dict:
client = Mistral()
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Analyze the sentiment."},
{"role": "user", "content": texte}
]
)
return {"sentiment": response.choices[0].message.content}
@workflows.activity(name="Send email notification")
async def envoyer_notification(destinataire: str, contenu: str) -> dict:
# ...
return {"status": "sent"}
Ponte en la piel del ingeniero de guardia que abre una vista de traza a las 3 de la mañana. Entre fetch_user_data y «Retrieve user profile», esto último es inmediatamente comprensible, incluso para alguien que nunca ha leído este código.
Recuperar trazas programáticamente
El SDK expone tres métodos de acceso bajo client.workflows.executions; sus versiones asíncronas llevan el sufijo _async. El primero devuelve datos OpenTelemetry en bruto: spans, duraciones, atributos, relaciones padre-hijo, lo que te permite volver a ingerirlos en tu propia herramienta de observabilidad (Jaeger, Grafana Tempo, etc.).
from mistralai.client import Mistral
client = Mistral()
# Datos OpenTelemetry en bruto para la ejecución
trace = await client.workflows.executions.get_workflow_execution_trace_otel_async(
execution_id="exec_abc123def456"
)
print(f"OTel Trace: {trace.otel_trace_id}")
otel_data = trace.otel_trace_data # Traza completa, para reexportar a tu backend
Cuando principalmente quieras saber si la ejecución tuvo éxito y cuánto tardó, el resumen es suficiente. Incluye el estado, la duración total y el árbol de spans, que puedes recorrer recursivamente:
summary = await client.workflows.executions.get_workflow_execution_trace_summary_async(
execution_id="exec_abc123def456"
)
print(f"Workflow: {summary.workflow_name} — estado {summary.status}")
print(f"Duración total: {summary.total_duration_ms} ms")
def display(span, depth=0):
end = span.end_time_unix_nano or span.start_time_unix_nano
duration_ms = (end - span.start_time_unix_nano) / 1e6
print(f"{' ' * depth}{span.name}: {duration_ms:.0f} ms, {len(span.events)} evento(s)")
for child in span.children or []:
display(child, depth + 1)
if summary.span_tree:
display(summary.span_tree)
El tercer método devuelve una lista cronológica de eventos de ejecución:
response = await client.workflows.executions.get_workflow_execution_trace_events_async(
execution_id="exec_abc123def456",
include_internal_events=False, # Excluir eventos internos de la plataforma
)
for event in response.events or []:
print(event)
El parámetro include_internal_events=False filtra los eventos técnicos de la plataforma, manteniendo solo los de tu flujo de trabajo y actividades. En un flujo de trabajo ligeramente largo, la diferencia en legibilidad es considerable. Para los propios registros (logs), aquellos que se muestran en Studio, get_workflow_execution_logs los devuelve página por página.
Dominar el muestreo
Por defecto, todas las trazas se exportan: el trabajador muestrea al 100 %. Para establecer el ID de traza o controlar el muestreo de una ejecución, pasa un traceparent en formato W3C en el cuerpo de la solicitud de ejecución. El trabajador utiliza un muestreador basado en el padre: sigue tu decisión, llevada por el último campo (01 para recopilar, 00 para no recopilar).
execution = await client.workflows.execute_workflow_async(
workflow_identifier="my_workflow",
input={"data": "test"},
traceparent="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
)
Los SDK de Mistral hacen esto automáticamente: con cada ejecución, transmiten el traceparent del span actual. Pasar traceparent en una cabecera HTTP sigue siendo aceptado pero está obsoleto, porque una cabecera puede reescribirse en tránsito; usa el parámetro en su lugar.
Monitorizar en producción
Cinco indicadores son suficientes para mantener un flujo de trabajo bajo control: la tasa de éxito, es decir, el porcentaje de ejecuciones que terminan sin error; la duración media de una ejecución completa; las duraciones P95 y P99, que revelan las ejecuciones más lentas que la media oculta; la tasa de reintentos por actividad, cuyo aumento repentino delata un servicio externo inestable mucho antes de que la tasa de éxito se degrade; y finalmente, la identificación de la actividad más lenta, tu cuello de botella.
Dado que las trazas respetan el estándar OpenTelemetry, nada te obliga a consultarlas desde el SDK: pueden exportarse a Datadog a través de su colector OTel, a Grafana y Tempo por el mismo mecanismo, a Jaeger para la visualización de trazas distribuidas, o a New Relic a través de su exportador dedicado. Tus flujos de trabajo se unen así al panel donde ya vive el resto de tu infraestructura.
Depurar un flujo de trabajo fallido
Ante un fallo, un procedimiento metódico evita las conjeturas.
- Recuperar el ID de ejecución de los registros o la respuesta de la API.
- Consultar el resumen de la traza para conocer el estado y detectar la actividad defectuosa en el árbol de spans.
- Examinar los eventos detallados para comprender la secuencia que llevó al error.
- Comprobar los reintentos: ¿se reinició la actividad? ¿Cuántas veces?
- Analizar el mensaje de error: ¿tiempo de espera agotado, error de red, error de negocio?
Los dos primeros pasos pueden scriptarse en pocas líneas, usando la función display vista anteriormente, lo que te proporciona una herramienta de diagnóstico reutilizable.
async def diagnose_failure(execution_id: str):
client = Mistral()
executions = client.workflows.executions
# Paso 1: Resumen y árbol de spans
summary = await executions.get_workflow_execution_trace_summary_async(execution_id=execution_id)
print(f"Estado: {summary.status}")
if summary.span_tree:
display(summary.span_tree)
# Paso 2: Eventos de tu código, en orden
response = await executions.get_workflow_execution_trace_events_async(
execution_id=execution_id,
include_internal_events=False,
)
for event in response.events or []:
print(event)
El número de intentos merece una atención especial: una actividad que falla en el primer intento y otra que falla tras cinco reintentos cuentan historias diferentes y requieren correcciones distintas.
Resumen del curso
Enhorabuena, has terminado este curso sobre Mistral Workflows. El viaje te llevó desde la orquestación durable y el mecanismo de event sourcing hasta la instalación del SDK (lecciones 1 a 3), pasando por la creación de actividades, flujos de trabajo y trabajadores, su desencadenamiento y prueba (lecciones 4 a 7). Las lecciones 8 a 11 establecieron las restricciones de estructuración: determinismo, entradas Pydantic, tiempos de espera y limitaciones, antes de abrirse a patrones avanzados de paralelismo y continuación. Las tres últimas cubrieron las políticas de reintento, el requisito de E/S asíncrona y la observabilidad con OpenTelemetry.
La plataforma está en Vista Previa Pública: las API y las funciones pueden evolucionar. Consulta la documentación oficial regularmente en docs.mistral.ai/workflows para seguir las actualizaciones.
Puntos clave
- Cada actividad genera automáticamente spans de OpenTelemetry con nombre, duración y estado.
- Nombra tus actividades con el parámetro
namepara facilitar la depuración. - Tres métodos para acceder a las trazas, bajo
client.workflows.executions: OTel en bruto, resumen (estado, duración, árbol de spans) y eventos detallados. - El muestreo se controla mediante el parámetro
traceparentde la ejecución (100 % por defecto; la cabecera HTTP está obsoleta). - En producción, monitoriza la tasa de éxito, la duración y la tasa de reintentos.
- Las trazas OTel estándar son exportables a Datadog, Grafana, Jaeger o New Relic.
Pon a prueba tus conocimientos
Flujos de trabajo durables: reglas del motor antes de la producción.
1. ¿Qué garantiza la plataforma Mistral Workflows?
Respuesta: Durabilidad: un flujo de trabajo sobrevive a los fallos y se reanuda donde lo dejó; la orquestación de larga duración se vuelve fiable por diseño.
2. Actividad, flujo de trabajo, trabajador: ¿quién hace qué?
Respuesta: La actividad es la unidad de trabajo (llamada externa, cálculo), el flujo de trabajo orquesta las actividades, el trabajador ejecuta; la separación que permite la reanudación y el escalado.
3. ¿Qué impone la regla de determinismo?
Respuesta: El código del flujo de trabajo debe ser reproducible idénticamente: sin aleatoriedad ni acceso directo al reloj en la orquestación; los efectos no deterministas viven en las actividades.
4. ¿Cómo se gestionan los fallos transitorios?
Respuesta: Mediante la política de reintentos de la actividad (intentos, retroceso) y los tiempos de espera; el fallo es un caso normal, gestionado de forma declarativa en lugar de manual.
5. ¿Qué aporta la integración de OpenTelemetry?
Respuesta: Observabilidad estándar: trazas de ejecución, métricas y correlación con el resto de tu sistema; esencial para operar flujos de trabajo en producción.
Durabilidad, determinismo, reintentos, observabilidad: cuatro reglas que mantienen unidas las orquestaciones de larga duración; el motor se encarga del resto.