Traces, History, and Performance

Execution Traces

Traces are the detailed record of everything that happens during a workflow execution. Each node generates traces with input, output, error, and timing information.

What is Recorded

Each trace contains:

Field	Description
workflow_id	Unique execution identifier
workflow_name	Workflow name
module_name	Name of the node that generated the trace
node_id	Node ID in the editor
step	Description of the executed step
details	Detailed data in JSON (input, output, metadata)
level	Trace level (see table below)
session_id	Session ID to group traces from the same execution
timestamp	Exact date and time

Trace Levels

Level	Usage	When it appears
TRACE	Detailed execution flow	Input and output of each node, variable resolutions
DEBUG	Debugging information	Intermediate data, internal states
INFO	General information	Execution start/end, main results
WARN	Warnings	Missing optional data, retries, unexpected responses
ERROR	Errors	Node failures, connection errors, exceptions

Real-Time Traces

Traces are transmitted in real time via WebSocket to connected clients. This allows viewing a workflow execution live:

1. The client connects to the WebSocket
2. Sets filters with setFilters: specific workflow, event type, etc.
3. Receives workflowEvent events with each generated trace
4. Only receives traces matching their filters

Development vs Production URL

• /webhooks-dev/{hash}: Activates detailed traces (TRACE level). Use for debugging.
• /webhooks/{hash}: Production mode with minimal traces. Use in real environments.

Querying Traces

Endpoint	Description
GET /api/traces	List traces with filters (workflow, module, level, dates)
GET /api/traces/:workflowId	Traces for a specific execution
GET /api/traces/workflow/:name	Traces by workflow name
GET /api/traces/module/:name	Traces for a specific module
GET /api/traces/levels/summary	Summary by level (last 24h)
GET /api/traces/search/:term	Full-text search in traces
GET /api/traces/stats	Storage statistics

Trace Cleanup

Traces are automatically cleaned up according to the client’s plan (retention days). They can also be cleaned up manually:

Endpoint	Description
DELETE /api/traces/cleanup	Manual cleanup (specify days to retain)
DELETE /api/traces/cleanup/by-plan	Cleanup according to plan limits
DELETE /api/traces/workflow/:id	Delete traces for a specific workflow
DELETE /api/traces/clear-all	Delete all client history

---

Execution History

The history records each execution of each workflow with the state of each node: what data it received, what it returned, how long it took, and whether there were errors.

What is Stored per Node

Field	Description
workflow_id	Unique execution hash (e.g.: wf_abc123)
module_name	Name of the executed node
status	Status: completed, failed, delayed
data	Node input data (JSON)
result	Node output data (JSON)
retries	Number of retries performed
error_message	Error message (if failed)
response_time_ms	Execution time in milliseconds
last_execution	Date and time of the last execution
steps	JSON array with the accumulated step history

Execution Instances

Each time a workflow executes, a unique instance is created in the workflowinstances table:

Field	Description
workflow_id	Unique instance hash (wf_xxx)
workflow_name	Workflow name
workflow_parent_id	Template workflow ID (to link multiple executions)
created_at	When the execution started

This allows querying all executions of a specific workflow, comparing executions with each other, and detecting trends.

Querying History

Endpoint	Description
GET /api/workflow/stats/:id	Complete workflow statistics
GET /api/workflow/stats/:id/nodes	Statistics per node
GET /api/workflow/stats/:id/errors	Error distribution
GET /api/workflow/stats/:id/sessions	Last 20 execution sessions
GET /api/workflow/stats/:id/timeline	Execution timeline (for waterfall visualization)

Session Data

For each execution session you can see:

• Total execution duration
• Number of traces generated
• Whether there were errors and in which node
• Final status (successful or failed)

---

Performance Summary and Analysis

The platform provides detailed metrics to analyze the performance of each workflow and each individual node.

Global Workflow Metrics

When querying GET /api/workflow/stats/:id, you get:

{
  "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": [ ... ]
}

Metric	Description
total_executions	Total number of workflow executions
success_rate	Percentage of successful executions
error_rate	Percentage of executions with errors
total_errors	Total number of failed executions
avg_duration	Average execution time in milliseconds
nodes_used	List of modules used

Per-Node Metrics

Each node has its own statistics:

Metric	Description
total_executions	Times the node was executed
avg_duration	Average node time (ms)
max_duration	Maximum recorded time (ms)
error_count	Number of node failures
success_rate	Node success percentage

This allows identifying bottlenecks: if an HTTP node takes an average of 3 seconds while the rest take milliseconds, you know where to optimize.

Execution Trend

The execution_trend field shows executions over the last 10 days, grouped by date:

[
  { "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 }
]

Useful for detecting activity spikes, increases in error rates, or changes after a workflow modification.

Error Analysis

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

• Error distribution by node (which nodes fail the most)
• Error message grouping (repetitive errors)
• Top 20 most frequent errors

This allows prioritizing fixes: if 80% of errors are “timeout” on an HTTP node, the solution is to adjust the timeout or improve the target API.

Timeline View (Waterfall)

GET /api/workflow/stats/:id/timeline provides the chronological execution sequence of each node, ideal for visualizing:

• The actual execution order
• Nodes that execute in parallel
• Where execution time is concentrated
• Wait points (delays, merges)