Handit Tracing icon

Handit Tracing

Collect workflow data and send to Handit API for tracing
Join our community

Overview

The Handit Tracing node collects workflow execution data from specified nodes and sends this information to the Handit API for tracing and analysis. It is designed to help users monitor and debug their workflows by providing detailed trace data about node executions, including inputs, outputs, timestamps, and custom metadata.

This node is particularly useful in scenarios where you want to:

  • Track the behavior of specific nodes within a workflow.
  • Collect execution metadata for auditing or debugging purposes.
  • Integrate workflow execution data with external monitoring or analytics platforms.

For example, if you have a workflow that processes messages from Telegram and performs AI-based transformations, you can use this node to trace the execution of nodes like "Telegram Trigger", "AI Agent", and "Edit Fields" to understand how data flows through these steps and identify any issues.

Properties

Name Meaning
Operation The action to perform; currently supports only "Trace Workflow" which collects and sends workflow data.
User Token Your Handit user token used for authenticating requests to the Handit API.
Node Names Comma-separated list of node names to trace. If left empty, defaults to tracing: "Telegram Trigger", "Edit Fields", "AI Agent", "Telegram".
Additional Fields A collection of optional fields to add context to the trace:
- Workflow ID Custom identifier for the workflow being traced.
- User ID Identifier for the user associated with the trace.
- Environment The environment where the workflow runs; options are Development, Staging, or Production (default).

Output

The node outputs an array of JSON objects, each representing the result of a trace attempt for one input item. Each object contains:

  • success: Boolean indicating if the trace was successful.
  • response: The response from the Handit API when successful.
  • tracedNodes: Number of nodes traced in this operation.
  • payload: The full payload sent to the Handit API, including:
    • workflowData: An array of objects for each traced node containing:
      • slug: The node name.
      • input: Object with node name, timestamp, additional fields, and previous intermediate steps if available.
      • output: The output data from the node.
      • error (optional): Error message if tracing that node failed.
    • timestamp: Timestamp of the trace request.
    • executionId: The current workflow execution ID or "unknown" if unavailable.
    • workflowId: The custom workflow ID or "unknown" if not provided.
  • error: Present if the trace failed, containing the error message.
  • timestamp: Timestamp of the failure.

The node does not output binary data.

Dependencies

  • Requires an active internet connection to send HTTP POST requests to the Handit API endpoint at https://handit-api-oss-299768392189.us-central1.run.app/api/track.
  • Needs a valid user token for authentication with the Handit API.
  • Uses an API key credential configured in n8n (referred generically as "an API key credential") for authenticated requests.
  • No other external dependencies.

Troubleshooting

  • Common Issues:

    • Invalid or missing user token will cause authentication failures.
    • Incorrect node names may result in empty or incomplete trace data.
    • Network connectivity issues can prevent sending data to the Handit API.
    • Missing or malformed input data might lead to partial traces or errors.

  • Error Messages:

    • Errors returned from the Handit API will be included in the output under the error field.
    • If the node fails to send data, it returns an error message describing the issue.

  • Resolutions:

    • Ensure the user token is correct and has necessary permissions.
    • Verify node names are spelled exactly as they appear in the workflow.
    • Check network connectivity and proxy settings if applicable.
    • Confirm input data structure matches expected format, especially presence of intermediate steps if needed.

Links and References

Discussion