Trazas, historial y rendimiento

Trazas de ejecucion (Traces)

Las trazas son el registro detallado de todo lo que ocurre durante la ejecucion de un workflow. Cada nodo genera trazas con informacion de entrada, salida, errores y tiempos.

Que se registra

Cada traza contiene:

Campo	Descripcion
workflow_id	Identificador unico de la ejecucion
workflow_name	Nombre del workflow
module_name	Nombre del nodo que genero la traza
node_id	ID del nodo en el editor
step	Descripcion del paso ejecutado
details	Datos detallados en JSON (entrada, salida, metadata)
level	Nivel de la traza (ver tabla abajo)
session_id	ID de sesion para agrupar trazas de una misma ejecucion
timestamp	Fecha y hora exacta

Niveles de traza

Nivel	Uso	Cuando aparece
TRACE	Flujo detallado de ejecucion	Entrada y salida de cada nodo, resoluciones de variables
DEBUG	Informacion de depuracion	Datos intermedios, estados internos
INFO	Informacion general	Inicio/fin de ejecucion, resultados principales
WARN	Advertencias	Datos opcionales faltantes, reintentos, respuestas inesperadas
ERROR	Errores	Fallos de nodos, errores de conexion, excepciones

Trazas en tiempo real

Las trazas se transmiten en tiempo real via WebSocket a los clientes conectados. Esto permite ver la ejecucion de un workflow en vivo:

El cliente se conecta al WebSocket
Define filtros con setFilters: workflow especifico, tipo de evento, etc.
Recibe eventos workflowEvent con cada traza generada
Solo recibe las trazas que coinciden con sus filtros

URL de desarrollo vs produccion

/webhooks-dev/{hash}: Activa trazas detalladas (nivel TRACE). Usar para depuracion.
/webhooks/{hash}: Modo produccion con trazas minimas. Usar en entornos reales.

Consultar trazas

Endpoint	Descripcion
`GET /api/traces`	Listar trazas con filtros (workflow, modulo, nivel, fechas)
`GET /api/traces/:workflowId`	Trazas de una ejecucion especifica
`GET /api/traces/workflow/:name`	Trazas por nombre de workflow
`GET /api/traces/module/:name`	Trazas de un modulo especifico
`GET /api/traces/levels/summary`	Resumen por nivel (ultimas 24h)
`GET /api/traces/search/:term`	Busqueda de texto completo en trazas
`GET /api/traces/stats`	Estadisticas de almacenamiento

Limpieza de trazas

Las trazas se limpian automaticamente segun el plan del cliente (dias de retencion). Tambien se pueden limpiar manualmente:

Endpoint	Descripcion
`DELETE /api/traces/cleanup`	Limpieza manual (especificar dias a conservar)
`DELETE /api/traces/cleanup/by-plan`	Limpieza segun limites del plan
`DELETE /api/traces/workflow/:id`	Eliminar trazas de un workflow especifico
`DELETE /api/traces/clear-all`	Eliminar todo el historial del cliente

Historial de ejecuciones

El historial registra cada ejecucion de cada workflow con el estado de cada nodo: que datos recibio, que devolvio, cuanto tardo y si hubo errores.

Que se almacena por nodo

Campo	Descripcion
workflow_id	Hash unico de la ejecucion (ej: wf_abc123)
module_name	Nombre del nodo ejecutado
status	Estado: completed, failed, delayed
data	Datos de entrada del nodo (JSON)
result	Datos de salida del nodo (JSON)
retries	Numero de reintentos realizados
error_message	Mensaje de error (si fallo)
response_time_ms	Tiempo de ejecucion en milisegundos
last_execution	Fecha y hora de la ultima ejecucion
steps	Array JSON con el historial acumulado de pasos

Instancias de ejecucion

Cada vez que un workflow se ejecuta, se crea una instancia unica en la tabla workflowinstances:

Campo	Descripcion
workflow_id	Hash unico de la instancia (wf_xxx)
workflow_name	Nombre del workflow
workflow_parent_id	ID del workflow plantilla (para vincular multiples ejecuciones)
created_at	Cuando se inicio la ejecucion

Esto permite consultar todas las ejecuciones de un workflow especifico, comparar ejecuciones entre si, y detectar tendencias.

Consultar historial

Endpoint	Descripcion
`GET /api/workflow/stats/:id`	Estadisticas completas de un workflow
`GET /api/workflow/stats/:id/nodes`	Estadisticas por nodo
`GET /api/workflow/stats/:id/errors`	Distribucion de errores
`GET /api/workflow/stats/:id/sessions`	Ultimas 20 sesiones de ejecucion
`GET /api/workflow/stats/:id/timeline`	Linea de tiempo de ejecucion (para visualizacion waterfall)

Datos de una sesion

Para cada sesion de ejecucion se puede ver:

Duracion total de la ejecucion
Cantidad de trazas generadas
Si hubo errores y en que nodo
Estado final (exitoso o fallido)

Resumen y analisis de rendimiento

La plataforma proporciona metricas detalladas para analizar la performance de cada workflow y cada nodo individual.

Metricas globales del workflow

Al consultar GET /api/workflow/stats/:id, se obtiene:

{
  "total_executions": 1250,
  "success_rate": 97.5,
  "error_rate": 2.5,
  "total_errors": 31,
  "avg_duration": 2340,
  "nodes_used": ["Webhook", "HTTP", "Decision", "SendMail", "End"],
  "node_stats": { ... },
  "execution_trend": [ ... ]
}

Metrica	Descripcion
total_executions	Numero total de ejecuciones del workflow
success_rate	Porcentaje de ejecuciones exitosas
error_rate	Porcentaje de ejecuciones con errores
total_errors	Numero total de ejecuciones fallidas
avg_duration	Tiempo medio de ejecucion en milisegundos
nodes_used	Lista de modulos utilizados

Metricas por nodo

Cada nodo tiene sus propias estadisticas:

Metrica	Descripcion
total_executions	Veces que se ejecuto el nodo
avg_duration	Tiempo medio del nodo (ms)
max_duration	Tiempo maximo registrado (ms)
error_count	Cantidad de fallos del nodo
success_rate	Porcentaje de exito del nodo

Esto permite identificar cuellos de botella: si un nodo HTTP tarda en promedio 3 segundos mientras el resto tarda milisegundos, sabes donde optimizar.

Tendencia de ejecucion

El campo execution_trend muestra las ejecuciones de los ultimos 10 dias, agrupadas por fecha:

[
  { "date": "2026-03-20", "executions": 45, "errors": 1 },
  { "date": "2026-03-21", "executions": 52, "errors": 0 },
  { "date": "2026-03-22", "executions": 48, "errors": 3 },
  { "date": "2026-03-23", "executions": 38, "errors": 0 }
]

Util para detectar picos de actividad, incrementos en la tasa de error, o cambios tras una modificacion del workflow.

Analisis de errores

GET /api/workflow/stats/:id/errors devuelve:

Distribucion de errores por nodo (que nodos fallan mas)
Agrupacion de mensajes de error (errores repetitivos)
Top 20 errores mas frecuentes

Esto permite priorizar las correcciones: si el 80% de los errores son “timeout” en un nodo HTTP, la solucion es ajustar el timeout o mejorar la API destino.

Vista timeline (waterfall)

GET /api/workflow/stats/:id/timeline proporciona la secuencia cronologica de ejecucion de cada nodo, ideal para visualizar:

El orden real de ejecucion
Nodos que se ejecutan en paralelo
Donde se concentra el tiempo de ejecucion
Puntos de espera (delays, merges)