Trazas, historial y rendimiento

Trazas de ejecución (Traces)

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

Que se registra

Cada traza contiene:

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

Niveles de traza

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

Trazas en tiempo real

Las trazas se transmiten en tiempo real via WebSocket a los clientes conectados. Esto permite ver la ejecución 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 producción

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

Consultar trazas

Endpoint	Descripción
`GET /api/traces`	Listar trazas con filtros (workflow, modulo, nivel, fechas)
`GET /api/traces/:workflowId`	Trazas de una ejecución 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

Configuración de retención de trazas

Floogos permite controlar que trazas se almacenan y durante cuanto tiempo. Existen dos niveles de configuración que trabajan en conjunto:

Nivel de cliente (configuración global)

Ve a la pestaña Cuenta en tu perfil de usuario. La tarjeta Retención de trazas permite configurar:

Modo	Descripción
Completo	Se guardan todas las trazas (valor por defecto). Configura cuantos dias conservar (1-7).
Solo hoy	Solo se conservan las trazas del dia actual. Las anteriores se eliminan automáticamente.
Solo errores	Únicamente se guardan las ejecuciones fallidas. Las exitosas no dejan registro. Configura dias de retención (1-7).
Desactivado	No se escriben trazas. Máximo rendimiento, sin visibilidad.

Esta configuración aplica a todos los workflows de la cuenta salvo que un workflow la sobreescriba.

Nivel de workflow (sobreescritura por workflow)

En la lista de workflows, hace clic en el icono de edición (lapiz) de cualquier workflow. El selector Retención de trazas permite elegir:

Opción	Descripción
Heredar del cliente	Usa la configuración global del cliente (valor por defecto).
Completo	Siempre guarda todas las trazas para este workflow, independientemente de la configuración del cliente.
Solo hoy	Solo conserva las trazas del dia actual para este workflow.
Solo errores	Solo guarda trazas de error para este workflow.
Desactivado	Sin trazas para este workflow.

Jerarquia

Default del cliente → Sobreescritura por workflow (si no esta en "heredar")

Si un workflow esta en heredar, usa el modo del cliente. Si el workflow tiene un modo explicito, ese tiene prioridad.

Limpieza de trazas

Las trazas se limpian automáticamente según el plan del cliente (dias de retención). También se pueden limpiar manualmente:

Endpoint	Descripción
`DELETE /api/traces/cleanup`	Limpieza manual (especificar dias a conservar)
`DELETE /api/traces/cleanup/by-plan`	Limpieza según 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 ejecución 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	Descripción
workflow_id	Hash único de la ejecución (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	Número de reintentos realizados
error_message	Mensaje de error (si fallo)
response_time_ms	Tiempo de ejecución en milisegundos
last_execution	Fecha y hora de la última ejecución
steps	Array JSON con el historial acumulado de pasos

Instancias de ejecución

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

Campo	Descripción
workflow_id	Hash único de la instancia (wf_xxx)
workflow_name	Nombre del workflow
workflow_parent_id	ID del workflow plantilla (para vincular múltiples ejecuciones)
created_at	Cuando se inicio la ejecución

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

Consultar historial

Endpoint	Descripción
`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`	Distribución de errores
`GET /api/workflow/stats/:id/sessions`	Ultimas 20 sesiones de ejecución
`GET /api/workflow/stats/:id/timeline`	Línea de tiempo de ejecución (para visualización waterfall)

Datos de una sesión

Para cada sesión de ejecución se puede ver:

Duración total de la ejecución
Cantidad de trazas generadas
Si hubo errores y en que nodo
Estado final (exitoso o fallido)

Resumen y análisis de rendimiento

La plataforma proporciona métricas detalladas para analizar la performance de cada workflow y cada nodo individual.

Métricas 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": [ ... ]
}

Métrica	Descripción
total_executions	Número total de ejecuciones del workflow
success_rate	Porcentaje de ejecuciones exitosas
error_rate	Porcentaje de ejecuciones con errores
total_errors	Número total de ejecuciones fallidas
avg_duration	Tiempo medio de ejecución en milisegundos
nodes_used	Lista de modulos utilizados

Métricas por nodo

Cada nodo tiene sus propias estadisticas:

Métrica	Descripción
total_executions	Veces que se ejecuto el nodo
avg_duration	Tiempo medio del nodo (ms)
max_duration	Tiempo máximo 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 ejecución

El campo execution_trend muestra las ejecuciones de los últimos 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 }
]

Útil para detectar picos de actividad, incrementos en la tasa de error, o cambios tras una modificación del workflow.

Análisis de errores

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

Distribución de errores por nodo (que nodos fallan mas)
Agrupación 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 solución es ajustar el timeout o mejorar la API destino.

Vista timeline (waterfall)

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

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