Debugging Workflows

Development of any application requires the use of tools for checking data at various steps; tracing the steps a given input followed through a program; and benchmarking performance for different inputs and methods of arriving at a desired output. For Losant Workflows, we expose these tools through a debug panel, which is accessible in the right column of the workflow editor.

Workflow debug messages provide three pieces of information that are essential to debugging workflows and improving performance:

• Full payload data at the time a message was invoked, including any mutations made up to the point the message was sent.
• An execution path of which nodes preceded the node that recorded the message, detailing how node configurations respond to a given input.
• Per-node execution times for identifying performance bottlenecks and testing alternative approaches to arriving at desired outputs.

Debug streams are ephemeral–meaning that generated messages are not stored by Losant. Thus, they are only accessible while a user is connected to a debug stream, and the content is discarded as soon as the web browser navigates away from the workflow.

Viewing Debug Output

Debug messages can be found in the debug panel within the workflow editor. New messages appear in this panel automatically as they are received. If the panel is collapsed, an icon will appear in the debug tab indicating the there are new messages to view since the last time the panel was open.

Hovering your mouse over a debug message will highlight the path of the workflow that led to the node that produced the output. This allows for a quick visualization of which nodes were executed and which branches were taken (i.e. in Conditional Nodes and Switch Nodes).

Depending on the type of workflow being viewed, there are some behavior differences to note about the debug panel.

Application Workflows

When viewing an Application Workflow, all messages generated by all versions of the workflow will appear in the debug panel. While the message itself, including the payload and timing information, can be read regardless of which version you are currently viewing, the path the nodes took to reach the source of the debug message can only be viewed when the workflow editor is displaying the same version that generated the debug message.

Experience Workflows

Experience Workflows, by contrast, only display messages generated by the version currently being viewed.

Custom Nodes

Executions of Custom Node instances within your workflows (as in, invocations of the node) do not appear in the debug panel. Rather, only messages generated through the pressing of the Virtual Button within the node’s editor appear. (The Virtual Button Trigger is provided to allow for debugging Custom Nodes during their development.)

Edge & Embedded Workflows (Live Look)

Viewing debug output for an Edge Workflow or an Embedded Workflow is quite different from viewing the output for workflows that execute in Losant’s cloud environment. Debugging requires:

• Choosing a specific device …
• That is currently connected to Losant’s MQTT broker …
• And has a version of the workflow deployed to it.

To facilitate this, Losant provides a “Live Look” into a device that automatically displays the version running on the device and connects to the device’s debug stream.

The Live Look can be accessed through two different methods:

From a Workflow

While viewing a workflow, open the “Devices” tab in the right column to see a list of devices that have a version of the workflow deployed to it (or with a pending deployment). Any device that is connected to the MQTT broker and has a version running will have a “Live Look” option in its dropdown menu. Select this option to launch the Live Look modal for that device, which will allow you to view debug output.

From a Device

You may also view all the workflows deployed to a given device by visiting the “Edge Compute” or “Embedded” tab (depending on the device class) on the device’s detail page. This displays a table of all workflows on (or actively deploying to) the device. You may launch the “Live Look” for any workflow on the device, provided the device is connected to the MQTT broker and the desired workflow version has completed deployment.

Debug Panel Options

The debug panel displays the most recently received 100 debug messages. At any time, you may pause the flow of messages into the panel, which is helpful for scrutinizing individual messages in high-volume workflows. Any messages received while the stream is paused will be queued, and unpausing the workflow will immediately add these messages to the panel.

At any time, you may also clear the current contents of the debug panel by clicking the “X” icon in the panel header.

In addition, there are a few options that will adjust the behavior of the debug panel:

• Automatically expand most recent message: When checked, the latest message to appear in the debug panel will expand to display the message body by default. Once a message is no longer the most recent within the panel, the body will collapse unless the user has explicitly collapsed and re-expanded the body already. Uncheck this option to not automatically expand the most recent message.
• Expand all properties: When checked, objects within a debug message will display all of their properties and sub-properties all the way down the message’s JSON structure by default. If unchecked, only the data property will be expanded to show its sub-properties by default. Note, users may expand or collapse any properties within the panel at any time regardless of this setting.
• Enable messages from custom nodes: If your workflow utilizes Custom Nodes, and those Custom Nodes have Debug Nodes within them, checking this option will display the messages produced within those Custom Nodes in the debug panel alongside messages produced by the workflow.

Types of Debug Messages

Debug messages can originate from a number of different sources within a workflow execution, and messages from all of these sources appear together, in chronological order, within the debug panel.

Debug Node Messages

The most common type of message that appears in the debug panel is those generated by Debug Nodes. These are messages the user explicitly opts in to receiving by placing these nodes within the run of a workflow, usually as the very last node at the end of a chain.

Regardless of where it appears in a run or the configuration applied to it, Debug Nodes have no impact on the behavior of a workflow; they do not mutate payload properties, and they take very little time to run (usually no more than 1ms).

You may add as many Debug Nodes to any workflow as you would like. A common practice when developing workflows, for example, is to place Debug Nodes before and after one or more other nodes to view how the execution of those nodes affects the payload.

Function Node Console Messages

Within a Function Node, you may utilize JavaScript’s console.log method to output custom messages or payload values to the workflow debug panel. Those messages will appear in the log as originating from the Function Node instance that produced the message.

Note that other console methods–such as console.time and console.timeEnd–will simply produce debug messages and will not provide the unique behavior of these other methods. They simply behave as the console.log method.

Custom Node Messages

When the “Enable messages from custom nodes” option is enabled, and your workflow makes use of Custom Nodes, and those Custom Nodes produce debug output through their execution, those debug messages will appear in the workflow’s debug panel as having originated from the instance of the Custom Node. Note that a given Custom Node may or may not produce any debug messages; whether a message is produced depends on the content of the custom node itself.

Fatal Error Messages

If any node throws an error that causes the workflow to halt execution, those messages will also appear in the debug panel. The messages will outline the encountered error and, like other debug messages, will display the payload as it was at the time of the node’s execution.

Workflow-level errors (such as timeouts) will also appear in the debug panel, though per-node timing information may not be available in these cases.

Such errors will also appear in the Workflow Metrics tab, though they may take up to 15 minutes before being reflected in that tab.

Throttle Limit Messages

A workflow will only output a maximum of 10 debug messages per half-second. If that limit is exceeded, the debug stream will publish an additional message to notify the user that the throttle limit has been reached and that some debug messages are not being displayed.

Cases where you may run into debug message throttling include:

• Workflows that run on a very high frequency, such as those kicked off by Device: State Triggers matching a large number of devices that report state several times per minute.
• Workflows that utilize Debug Nodes inside of Loop Nodes. Depending on how long each iteration of the loop takes to execute, you may hit this throttle limit.
• Workflow paths that utilize multiple Debug Nodes in a single run, as these will produce one debug message per node.
• Numerous console.log messages within a Function Node.

Workflow Node Timing

In addition to displaying the payload at the time a debug message was delivered, each message also contains detailed, per-node execution timing information for all nodes preceding and including the node that triggered the debug message. This is helpful for identifying nodes that take especially long to execute (for example, when interacting with a third-party API using an HTTP Node).

Per-node debug timing is displayed as a waterfall chart under the “Timing” tab of each debug message, with a line dedicated to each node in the execution path. Furthermore, the total elapsed time from the trigger to the message-generating node is also displayed in the header of each debug message.

Loop Node Timing

Loop Nodes are a special case when it comes to workflow node timing:

• For messages generated outside of a loop (such as a Debug Node following a Loop Node), the Loop Node is treated as a single entry in the timing table as if it were any other node in the run, with the total time to execute all iterations of the loop aggregated into one line.
• For messages generated inside of a loop (such as a Debug Node within a loop’s contents), message timing is for the individual iteration of the loop that generated the message. In other words, the timing calculation begins with the iteration of the loop and ends at the point where the debug message was generated. Note: Debug Nodes inside of loops can generate a large quantity of messages in a short period of time, which can lead to your debug stream hitting throttling limits.

Note: Embedded Workflows, as well as Edge Workflows running on Gateway Edge Agent v1.23.0 or earlier, do not include workflow node timing data.

Debug Stream Errors

Should a debug stream become disconnected, the debug icon will turn red to indicate the problem. In such a case, the workflow may still be executing in response to the triggers contained within, but any debug messages generated by that workflow run will not appear.

Also, messages generated in the stream downtime will not appear in the debug panel after it reconnects. For this reason, the absence of a debug message does not mean that a workflow did not execute when the stream is disconnected or throttled.