Tracking Burr

Note

Burr’s telemetry system is built in and easy to integrate. It allows you to understand the flow of your application, and watch it make decisions in real time. You can run it with sample projects by running burr in the terminal after pip install "burr[start]".

Burr comes with a telemetry system that allows tracking a variety of information for debugging, both in development and production.

The data model for tracking is simple:

  1. Projects are the top-level grouping of data (the first page). This is specified in the constructor for the with_tracker, as the only required argument.

  2. Applications get logged to projects. An application would be considered similar to a “trace” in distributed tracing systems. This is (optionally) specified as the app_id argument for the with_tracker method. A single application has shared state path across all its steps.

  3. Steps are the individual steps that are executed in the state machine. The Burr UI will show the state of the state machine at the time of the step execution, as well as the input to and results of the step.

Tracking Client

When you use with_tracker, you add a tracker to Burr. This is a lifecycle hook that does the following:

  1. Logs the static representation of the state machine

  2. Logs any information before/after step execution, including

    • The step name

    • The step input

    • The state at time of execution

    • The timestamps

This currently defaults to (and only supports) the LocalTrackingClient class, which writes to a local file system, although we will be making it pluggable in the future. It will, by default, write to the directory ~/.burr.

Debugging via Reloading Prior State

Because the tracking client writes to the file system, you can reload the state of the state machine at any time. This is useful for debugging, because you can quickly recreate the issue by running the state machine with the same point in time.

To do so, you’d use the classmethod _load_state()_ on the LocalTrackingClient.

For example, as you initialize the Burr Application, you’d have some control flow like this:

from burr.tracking import client

project_name = "demo_hamilton-multi-agent"
if app_instance_id:
    initial_state, entry_point = client.LocalTrackingClient.load_state(
        project_name, app_instance_id
    )
    # TODO: any custom logic for re-creating the state if it's some object that needs to be re-instantiated
else:
    initial_state, entry_point = default_state_and_entry_point()

app = (
    ApplicationBuilder()
    .with_state(**initial_state)
    .with_entry_point(entry_point)
    # ... etc fill in the rest here
)

Tracking Server

The tracking server (now) is meant for visualizing the state machine and the steps that have been executed. You can run it with the following command:

burr

This will start a server on port 7241, and open up a browser window with the UI for you to explore.

Using Burr in Google Collab

If you run Burr in Google Collab, you can use the following code to expose the Burr UI to your browser:

# in one cell - expose the port:
from google.colab import output
output.serve_kernel_port_as_window(7241)

# in another cell - start burr: (! denotes a command line call)
!burr &
# now click the localhost:7241 from the prior cell.
# It should open up a new tab with the burr UI!