Skip to content

armgit / burr

Public Imported from GitHub
0

Build applications that make decisions (chatbots, agents, simulations, etc...). Monitor, trace, persist, and execute on your own infrastructure.

Adds documentation on local tracking

elijahbenizzyf830c0514101
diff --git a/burr/core/application.py b/burr/core/application.py
index e7b18c3b..d9e84ab5 100644
--- a/burr/core/application.py
+++ b/burr/core/application.py
@@ -645,6 +645,16 @@ class ApplicationBuilder:
def with_tracker(
self, project: str, tracker: Literal["local"] = "local", params: Dict[str, Any] = None
):
+ """Adds a "tracker" to the application. The tracker specifies
+ a project name (used for disambiguating groups of tracers), and plugs into the
+ Burr UI. Currently the only supported tracker is local, which takes in the params
+ `storage_dir` and `app_id`, which have automatic defaults.
+
+ :param project: Project name
+ :param tracker: Tracker to use, currently only ``local`` is available
+ :param params: Parameters to pass to the tracker
+ :return: The application builder for future chaining.
+ """
if params is None:
params = {}
if tracker == "local":
diff --git a/burr/tracking/client.py b/burr/tracking/client.py
index 22cc0aac..890b4378 100644
--- a/burr/tracking/client.py
+++ b/burr/tracking/client.py
@@ -33,8 +33,9 @@ def _format_exception(exception: Exception) -> Optional[str]:
class LocalTrackingClient(PostApplicationCreateHook, PreRunStepHook, PostRunStepHook):
"""Tracker to track locally -- goes along with the Burr UI. Writes
down the following:
- 1. The whole application + debugging information (e.g. source code) to a file
- 2. A line for the start/end of each step"""
+ #. The whole application + debugging information (e.g. source code) to a file
+ #. A line for the start/end of each step
+ """
GRAPH_FILENAME = "graph.json"
LOG_FILENAME = "log.jsonl"
@@ -46,9 +47,9 @@ class LocalTrackingClient(PostApplicationCreateHook, PreRunStepHook, PostRunStep
app_id: Optional[str] = None,
):
"""Instantiates a local tracking client. This will create the following directories, if they don't exist:
- 1. The base directory (defaults to ~/.burr)
- 2. The project directory (defaults to ~/.burr/<project>)
- 3. The application directory (defaults to ~/.burr/<project>/<app_id>) on each
+ #. The base directory (defaults to ~/.burr)
+ #. The project directory (defaults to ~/.burr/<project>)
+ #. The application directory (defaults to ~/.burr/<project>/<app_id>) on each
On application create, it will write the state machine to the application directory.
On pre/post run step, it will write the start/end of each step to the application directory.
@@ -56,7 +57,7 @@ class LocalTrackingClient(PostApplicationCreateHook, PreRunStepHook, PostRunStep
:param project: Project name -- if this already exists it will be used, otherwise it will be created.
:param storage_dir: Storage directory
:param app_id: Unique application ID. If not provided, a random one will be generated. If this already exists,
- it will use that one/append to the files in that one.
+ it will use that one/append to the files in that one.
"""
if app_id is None:
app_id = f"app_{str(uuid.uuid4())}"
diff --git a/docs/concepts/index.rst b/docs/concepts/index.rst
index 86b3b3f9..838a972e 100644
--- a/docs/concepts/index.rst
+++ b/docs/concepts/index.rst
@@ -14,4 +14,5 @@ Overview of the concepts -- read these to get a mental model for how Burr works.
actions
transitions
hooks
+ tracking
planned-capabilities
diff --git a/docs/concepts/tracking.rst b/docs/concepts/tracking.rst
new file mode 100644
index 00000000..0face0c6
--- /dev/null
+++ b/docs/concepts/tracking.rst
@@ -0,0 +1,27 @@
+.. _tracking:
+
+=============
+Tracking Burr
+=============
+
+Burr comes with a telemetry system that allows tracking a variety of information for debugging,
+both in development and production. Note this is a WIP.
+
+---------------
+Tracking Client
+---------------
+
+When you use :py:meth:`burr.core.application.ApplicationBuilder.with_tracker`, you add a tracker to Burr.
+This is a lifecycle hook that does the following:
+
+#. Logs the static representation of the state machine
+#. 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 :py:class:`burr.tracking.LocalTrackingClient` class, which
+writes to a local file system, althoguh we will be making it pluggable in the future.
+
+This will be used with the UI, which can serve out of the specified directory. More coming soon!
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index 6e22292c..f6184f4b 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -15,5 +15,6 @@ need functionality that is not publicly exposed, please open an issue and we can
actions
state
conditions
+ tracking
lifecycle
integrations/index
diff --git a/docs/reference/tracking.rst b/docs/reference/tracking.rst
new file mode 100644
index 00000000..5af4094d
--- /dev/null
+++ b/docs/reference/tracking.rst
@@ -0,0 +1,12 @@
+========
+Tracking
+========
+
+Reference on the Tracking API. This is purely for information -- you should not use this directly.
+Rather, you should use this through :py:meth:`burr.core.application.ApplicationBuilder.with_tracker`
+
+
+.. autoclass:: burr.tracking.LocalTrackingClient
+ :members:
+
+ .. automethod:: __init__