From f830c0514101c5bc17bc23d0750276435d535f5f Mon Sep 17 00:00:00 2001 From: elijahbenizzy Date: Thu, 15 Feb 2024 13:24:46 -0800 Subject: [PATCH] Adds documentation on local tracking A WIP but I wanted to make it first-class. --- burr/core/application.py | 10 ++++++++++ burr/tracking/client.py | 13 +++++++------ docs/concepts/index.rst | 1 + docs/concepts/tracking.rst | 27 +++++++++++++++++++++++++++ docs/reference/index.rst | 1 + docs/reference/tracking.rst | 12 ++++++++++++ 6 files changed, 58 insertions(+), 6 deletions(-) create mode 100644 docs/concepts/tracking.rst create mode 100644 docs/reference/tracking.rst 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 @@ 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": 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 @@ 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/) - 3. The application directory (defaults to ~/.burr//) on each + #. The base directory (defaults to ~/.burr) + #. The project directory (defaults to ~/.burr/) + #. The application directory (defaults to ~/.burr//) 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 @@ def __init__( :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__