Adds documentation on local tracking

A WIP but I wanted to make it first-class.

burr/core/application.py

@@ -645,6 +645,16 @@ def with_hooks(self, *adapters: LifecycleAdapter) -> "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":

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,17 +47,17 @@ def __init__(
         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.
 
         :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())}"

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

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!

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

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__