Skip to Content
🎉 Welcome to handit.ai Documentation!
TracingGuidesAdvanced

Advanced Tracing

Complex node-by-node tracing for specialized use cases. This guide covers the advanced approach for granular control over individual operations.

Recommended approach: Use Manual Setup with the @tracing decorator for most use cases. This advanced approach is only needed for very specific specialized scenarios.

When to use advanced tracing

Use the advanced approach only when:

  • You need to trace individual LLM calls separately from agent workflows
  • You’re building custom monitoring tools that require granular operation data
  • You have complex agent architectures that don’t fit the standard agent pattern
  • You need backward compatibility with existing tracing implementations

For most use cases, the new simplified agent-level tracing is recommended.

Advanced node-by-node approach

This is the advanced approach that requires manual tracking of each operation:

Why this is complex: You must manually track every operation, manage execution IDs, and handle trace session lifecycle. The new @tracing decorator does all this automatically.

Advanced LLM node tracing

For tracking individual LLM calls outside of agent workflows:

Advanced tool tracing

For tracking individual tools outside of agent workflows:

Migration from advanced to simplified approach

If you’re using the advanced approach, here’s how to migrate:

Before (Advanced)

# Complex manual tracking
tracing_response = tracker.start_tracing(agent_name="agent")
execution_id = tracing_response.get("executionId")
 
try:
    result = await my_function()
    tracker.track_node(
        input=input_data,
        output=result,
        node_name="my_function",
        agent_name="agent",
        node_type="tool",
        execution_id=execution_id
    )
finally:
    tracker.end_tracing(execution_id=execution_id, agent_name="agent")

After (New Approach)

# Simple decorator
@tracing(agent="agent")
async def my_agent_function():
    result = await my_function()
    return result

Benefits of migration:

  • 90% less code required
  • Automatic operation capture
  • No manual session management
  • Cleaner, more maintainable code

Backward compatibility

The advanced approach still works and will continue to be supported for existing integrations. However, we recommend migrating to the new simplified approach when possible.

Migration strategy:

  1. Start with new agents using the @tracing decorator
  2. Gradually migrate existing agents when you have time
  3. Keep advanced code for complex scenarios that require granular control
  4. Use CLI setup for new projects to get the latest approach automatically

Need help migrating? Contact our support team for assistance with migrating from advanced tracing to the new simplified approach.

Next steps

Your autonomous engineer works best with the new simplified tracing approach combined with evaluation and GitHub integration.

Last updated on
Manual SetupIntroduction