Un workflow con 12 pasos, dos ramas condicionales y un bucle falla en la tercera iteración del segundo sub-paso del bucle. El mensaje de error dice “formato de respuesta inesperado”. ¿Por dónde empieza?
Sin datos de ejecución detallados, está adivinando. Con trazas de ejecución, ve exactamente lo que pasó — cada entrada, cada salida, cada límite de temporización, cada intento de reintento — en una vista jerárquica que refleja la estructura del workflow.
Qué capturan las trazas de ejecución
Cada ejecución de workflow produce una traza de ejecución: un árbol de spans que refleja el grafo de ejecución del workflow. Cada span registra:
- Identidad del paso — Qué paso, por ID y nombre
- Temporización — Hora de inicio, hora de fin y duración en milisegundos
- Entradas — Los valores exactos que se pasaron al paso después de la resolución de plantillas
- Salidas — El output estructurado que el paso produjo (o el error que lanzó)
- Intentos de reintento — Si el paso se reintentó, cada intento se registra con su error y el retraso de backoff antes del siguiente intento
- Contexto de anidamiento — Qué rama de una condición, qué iteración de un bucle, qué rama de un paso paralelo
Estructura jerárquica
El árbol de trazas sigue la estructura del workflow exactamente:
Ejecución del Workflow
├── Paso 1: Investigar prospecto (recipe) — 2.3s, éxito
├── Paso 2: Calificar lead (recipe) — 1.8s, éxito
├── Paso 3: Condición (score >= 70)
│ └── Rama entonces
│ ├── Paso 3a: Paralelo
│ │ ├── Rama A: Redactar correo — 3.1s, éxito
│ │ └── Rama B: Redactar mensaje LinkedIn — 2.7s, éxito
│ └── Paso 3b: Revisión (aprobación) — esperando
└── Paso 4: Archivar (omitido — la condición tomó la rama entonces)Las ramas condicionales muestran qué camino se tomó y por qué. Los bucles muestran cada iteración con su elemento y resultados de sub-pasos. Las ramas paralelas muestran ejecución concurrente con temporizaciones individuales.
Tres capas de observabilidad
Las trazas de ejecución son una de tres capas de observabilidad complementarias:
Trazas de ejecución (Firestore) son la herramienta detallada de inspección por ejecución. Alimentan la UI del inspector de ejecución y están diseñadas para depurar ejecuciones individuales. Cada ejecución obtiene una traza, y las trazas se retienen durante la vida del registro de ejecución.
Métricas de Prometheus rastrean la salud operativa agregada: ejecuciones totales, tasas de éxito, percentiles de duración y conteos de errores. Estos alimentan paneles de control y alertas — “la tasa de éxito del workflow X cayó por debajo del 95% en la última hora.”
Spans de OpenTelemetry proporcionan trazado distribuido a través de límites de servicio. El wrapper withSpan() crea spans para cualquier ruta de código instrumentada, llevando metadatos de workflow y paso. Estos se integran con cualquier backend compatible con OTel (Jaeger, Datadog, Honeycomb) para correlación de trazas entre sistemas.
Usando trazas para depurar
Encontrar el punto de fallo
Abra la página de detalle de la ejecución y expanda el árbol de trazas. Los pasos fallidos están resaltados. Haga clic en el paso fallido para ver sus entradas exactas y el mensaje de error. Compare las entradas con lo que esperaba — frecuentemente el problema es un paso anterior produciendo output inesperado que se pasa a un paso posterior.
Detectar problemas de resolución de plantillas
La traza de cada paso muestra los valores de entrada resueltos — después de la sustitución de plantillas. Si un paso esperaba {{step.research.company_name}} pero obtuvo undefined, la traza le muestra el valor resuelto real. Verifique si el paso referenciado produjo el campo de output esperado.
Identificar cuellos de botella de rendimiento
Ordene por duración para encontrar los pasos más lentos. Un paso que toma 15 segundos cuando pasos similares toman 2 segundos podría estar alcanzando un límite de velocidad, usando un modelo más caro de lo necesario, o procesando entrada inesperadamente grande.
Depurar comportamiento de reintentos
Cuando un paso se reintentó antes de tener éxito (o fallar permanentemente), la traza muestra cada intento: el error que activó el reintento, el retraso de backoff y el resultado del siguiente intento. Patrones comunes: límites de velocidad 429 transitorios (los reintentos tienen éxito después del backoff), errores 400 persistentes (todos los reintentos fallan con el mismo error — corrija la entrada, no el conteo de reintentos).
Las trazas son automáticas
No configura el trazado. Cada ejecución de workflow produce una traza, cada paso está instrumentado, y la traza se persiste de forma asíncrona (fire-and-forget) para que no ralentice la ejecución. El inspector de ejecuciones lee las trazas bajo demanda cuando abre la vista de detalle.
Las trazas de ejecución están disponibles en todos los planes. Las métricas de Prometheus y la integración con OpenTelemetry están disponibles en Enterprise. Conozca más sobre workflows o inicie su prueba gratuita.