From a7b475357e302cb90741712a33327832b3f8ba5f Mon Sep 17 00:00:00 2001 From: t1mato Date: Wed, 17 Jun 2026 18:31:06 -0700 Subject: [PATCH 1/2] docs: add dedicated Burr UI section to documentation (#411) * Adds docs/ui.rst as a top-level 'Burr UI' entry in the Sphinx sidebar, mirroring how Hamilton surfaces their UI * Covers quickstart, data model, notebook/Colab usage, FastAPI embedding, and See Also links to the tracking reference and monitoring deployment guides --- docs/index.rst | 1 + docs/ui.rst | 112 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 113 insertions(+) create mode 100644 docs/ui.rst diff --git a/docs/index.rst b/docs/index.rst index b30309bc7..fe81c02ca 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -25,6 +25,7 @@ :caption: Apache Burr getting_started/index + ui examples/index concepts/index reference/index diff --git a/docs/ui.rst b/docs/ui.rst new file mode 100644 index 000000000..0f9af1d5c --- /dev/null +++ b/docs/ui.rst @@ -0,0 +1,112 @@ +.. + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + + +.. _ui: + +======= +Burr UI +======= + +Burr comes with an open-source telemetry UI for monitoring, debugging, and replaying +your application runs in real time. It works locally out of the box and can also be +deployed alongside your production stack. + +.. image:: _static/chatbot.png + :alt: Burr UI showing a chatbot application graph + :align: center + +----------- +Quick Start +----------- + +Install Burr with the UI extras and launch the server: + +.. code-block:: bash + + pip install "apache-burr[start]" + burr + +This starts the tracking server on port ``7241`` and opens the UI in your browser. +Any application that uses :py:meth:`with_tracker ` +will automatically appear in the UI. + +.. code-block:: python + + app = ( + ApplicationBuilder() + .with_actions(...) + .with_transitions(...) + .with_tracker("local", project="my-project") + .build() + ) + +---------- +Data Model +---------- + +The UI is organized around three levels: + +1. **Projects** — the top-level grouping, set via the ``project`` argument to ``with_tracker``. +2. **Applications** — individual runs logged to a project, similar to a "trace" in distributed tracing. Set via the ``app_id`` argument. +3. **Steps** — each action executed in the state machine. The UI shows the state, inputs, and results at every step. + +------------------ +Notebook / Colab +------------------ + +Launch the UI from a Jupyter notebook or Google Colab using the ``%burr_ui`` IPython magic: + +.. code-block:: python + + # Expose the port and print the URL + %load_ext burr.integrations.notebook + %burr_ui + # → "Burr UI: http://127.0.0.1:7241" + +For Google Colab, forward the port to the browser: + +.. code-block:: python + + from google.colab import output + output.serve_kernel_port_as_window(7241) # opens a new window + output.serve_kernel_port_as_iframe(7241) # inline iframe + +-------------------------- +Embed in a FastAPI App +-------------------------- + +Mount the Burr UI inside an existing FastAPI application: + +.. code-block:: python + + from fastapi import FastAPI + from burr.tracking.server.run import mount_burr_ui + + app = FastAPI() + mount_burr_ui(app, path="/burr") + +The tracking UI will then be available at ``/burr`` on your existing server. + +-------- +See Also +-------- + +- :ref:`tracking` — full technical reference for the tracking client, data storage, and state replay +- :ref:`Additional Visibility ` — tracing, OpenTelemetry spans, and LLM instrumentation inside actions +- :doc:`examples/deployment/monitoring` — deploying the tracking server in production (local, S3, Docker) From 81ca828b411729ddfc98de023253abf0b895067b Mon Sep 17 00:00:00 2001 From: t1mato Date: Sun, 21 Jun 2026 22:58:39 -0700 Subject: [PATCH 2/2] docs: restructure Burr UI documentation into dedicated section for issue 411 * docs: restructure Burr UI documentation into dedicated section (#411) Add a dedicated docs/ui/ section covering the Burr UI from installation through notebook usage and production deployment, with focused pages for getting-started, notebook/Colab, and deployment. --- docs/index.rst | 2 +- docs/ui.rst | 112 ------------------------------------ docs/ui/deployment.rst | 58 +++++++++++++++++++ docs/ui/getting-started.rst | 89 ++++++++++++++++++++++++++++ docs/ui/index.rst | 50 ++++++++++++++++ docs/ui/notebook.rst | 58 +++++++++++++++++++ 6 files changed, 256 insertions(+), 113 deletions(-) delete mode 100644 docs/ui.rst create mode 100644 docs/ui/deployment.rst create mode 100644 docs/ui/getting-started.rst create mode 100644 docs/ui/index.rst create mode 100644 docs/ui/notebook.rst diff --git a/docs/index.rst b/docs/index.rst index fe81c02ca..8e3a90c8a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -25,7 +25,7 @@ :caption: Apache Burr getting_started/index - ui + ui/index examples/index concepts/index reference/index diff --git a/docs/ui.rst b/docs/ui.rst deleted file mode 100644 index 0f9af1d5c..000000000 --- a/docs/ui.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - - -.. _ui: - -======= -Burr UI -======= - -Burr comes with an open-source telemetry UI for monitoring, debugging, and replaying -your application runs in real time. It works locally out of the box and can also be -deployed alongside your production stack. - -.. image:: _static/chatbot.png - :alt: Burr UI showing a chatbot application graph - :align: center - ------------ -Quick Start ------------ - -Install Burr with the UI extras and launch the server: - -.. code-block:: bash - - pip install "apache-burr[start]" - burr - -This starts the tracking server on port ``7241`` and opens the UI in your browser. -Any application that uses :py:meth:`with_tracker ` -will automatically appear in the UI. - -.. code-block:: python - - app = ( - ApplicationBuilder() - .with_actions(...) - .with_transitions(...) - .with_tracker("local", project="my-project") - .build() - ) - ----------- -Data Model ----------- - -The UI is organized around three levels: - -1. **Projects** — the top-level grouping, set via the ``project`` argument to ``with_tracker``. -2. **Applications** — individual runs logged to a project, similar to a "trace" in distributed tracing. Set via the ``app_id`` argument. -3. **Steps** — each action executed in the state machine. The UI shows the state, inputs, and results at every step. - ------------------- -Notebook / Colab ------------------- - -Launch the UI from a Jupyter notebook or Google Colab using the ``%burr_ui`` IPython magic: - -.. code-block:: python - - # Expose the port and print the URL - %load_ext burr.integrations.notebook - %burr_ui - # → "Burr UI: http://127.0.0.1:7241" - -For Google Colab, forward the port to the browser: - -.. code-block:: python - - from google.colab import output - output.serve_kernel_port_as_window(7241) # opens a new window - output.serve_kernel_port_as_iframe(7241) # inline iframe - --------------------------- -Embed in a FastAPI App --------------------------- - -Mount the Burr UI inside an existing FastAPI application: - -.. code-block:: python - - from fastapi import FastAPI - from burr.tracking.server.run import mount_burr_ui - - app = FastAPI() - mount_burr_ui(app, path="/burr") - -The tracking UI will then be available at ``/burr`` on your existing server. - --------- -See Also --------- - -- :ref:`tracking` — full technical reference for the tracking client, data storage, and state replay -- :ref:`Additional Visibility ` — tracing, OpenTelemetry spans, and LLM instrumentation inside actions -- :doc:`examples/deployment/monitoring` — deploying the tracking server in production (local, S3, Docker) diff --git a/docs/ui/deployment.rst b/docs/ui/deployment.rst new file mode 100644 index 000000000..3d98f2a2a --- /dev/null +++ b/docs/ui/deployment.rst @@ -0,0 +1,58 @@ +.. + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + + +.. _ui-deployment: + +========== +Deployment +========== + +The Burr tracking server can be run locally for development or deployed alongside your +production stack for ongoing observability. + +-------------------------- +Embed in a FastAPI App +-------------------------- + +Mount the Burr UI inside an existing FastAPI application using the ``mount_burr_ui`` helper: + +.. code-block:: python + + from fastapi import FastAPI + from burr.tracking.server.run import mount_burr_ui + + app = FastAPI() + mount_burr_ui(app, path="/burr") + +The tracking UI will then be available at ``/burr`` on your existing server. + +-------------------- +Production Options +-------------------- + +For production deployments, Burr supports two tracking backends: + +1. **Local filesystem** (default) — suitable for development or lower-scale production + with a distributed filesystem. See :ref:`tracking` for configuration details. + +2. **S3-backed tracking** — designed for higher-scale production workloads. + See :ref:`s3-tracking-aws` for setup instructions. + +For full deployment examples including Docker Compose and nginx, see +:doc:`../examples/deployment/monitoring`. diff --git a/docs/ui/getting-started.rst b/docs/ui/getting-started.rst new file mode 100644 index 000000000..b205812de --- /dev/null +++ b/docs/ui/getting-started.rst @@ -0,0 +1,89 @@ +.. + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + + +.. _ui-getting-started: + +=============== +Getting Started +=============== + +----------- +Quick Start +----------- + +Install Burr with the UI extras and launch the server: + +.. code-block:: bash + + pip install "apache-burr[start]" + burr + +This starts the tracking server on port ``7241`` and opens the UI in your browser. + +------------------ +Connect Your App +------------------ + +Any application that uses :py:meth:`with_tracker ` +will automatically appear in the UI: + +.. code-block:: python + + from burr.core import ApplicationBuilder + + app = ( + ApplicationBuilder() + .with_actions(...) + .with_transitions(...) + .with_tracker("local", project="my-project") + .build() + ) + +Run your application and then open ``http://localhost:7241`` to see your project, +its application runs, and the step-by-step trace. + +----------------------- +Reloading Prior State +----------------------- + +Because the tracking client writes to the local filesystem (``~/.burr`` by default), you +can reload state from any past run for debugging: + +.. code-block:: python + + from burr.tracking import LocalTrackingClient + + tracker = LocalTrackingClient(project="my-project") + app = ( + ApplicationBuilder() + .with_graph(base_graph) + .initialize_from( + tracker, + resume_at_next_action=True, + default_state={}, + default_entrypoint="my-entrypoint", + fork_from_app_id="", + fork_from_sequence_id=None, + fork_from_partition_key=None, + ) + .with_tracker(tracker) + .build() + ) + +See :ref:`tracking` for the full tracking client reference. diff --git a/docs/ui/index.rst b/docs/ui/index.rst new file mode 100644 index 000000000..2c033bd21 --- /dev/null +++ b/docs/ui/index.rst @@ -0,0 +1,50 @@ +.. + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + + +.. _ui: + +======= +Burr UI +======= + +Burr comes with an open-source telemetry UI for monitoring, debugging, and replaying +your application runs in real time. It works locally out of the box and can also be +deployed alongside your production stack. + +.. image:: ../_static/chatbot.png + :alt: Burr UI showing a chatbot application graph + :align: center + +---------- +Data Model +---------- + +The UI is organized around three levels: + +1. **Projects** — the top-level grouping, set via the ``project`` argument to ``with_tracker``. +2. **Applications** — individual runs logged to a project, similar to a "trace" in distributed tracing. Set via the ``app_id`` argument. +3. **Steps** — each action executed in the state machine. The UI shows the state, inputs, and results at every step. + +.. toctree:: + :maxdepth: 1 + :hidden: + + getting-started + notebook + deployment diff --git a/docs/ui/notebook.rst b/docs/ui/notebook.rst new file mode 100644 index 000000000..5fae49d64 --- /dev/null +++ b/docs/ui/notebook.rst @@ -0,0 +1,58 @@ +.. + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + + +.. _ui-notebook: + +================ +Notebook / Colab +================ + +You can launch the Burr UI directly from a Jupyter notebook or Google Colab using the +``%burr_ui`` IPython magic, without needing a separate terminal. + +------------------ +Jupyter Notebook +------------------ + +.. code-block:: python + + # Load the extension and print the URL + %load_ext burr.integrations.notebook + %burr_ui + # → "Burr UI: http://127.0.0.1:7241" + +The magic starts the tracking server on port ``7241`` if it isn't already running and +prints the URL to access it. + +-------------- +Google Colab +-------------- + +In Colab, the kernel runs remotely, so you need to forward the port to your browser: + +.. code-block:: python + + %load_ext burr.integrations.notebook + %burr_ui + +.. code-block:: python + + from google.colab import output + output.serve_kernel_port_as_window(7241) # opens a new browser window + output.serve_kernel_port_as_iframe(7241) # or inline as an iframe