You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@burr.apache.org by sk...@apache.org on 2026/06/22 20:05:54 UTC
(burr) branch main updated: docs: restructure Burr UI documentation into dedicated section (#411) (#815)
This is an automated email from the ASF dual-hosted git repository.
skrawcz pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/burr.git
The following commit(s) were added to refs/heads/main by this push:
new ce297d21 docs: restructure Burr UI documentation into dedicated section (#411) (#815)
ce297d21 is described below
commit ce297d2181493f99e19608113d70d88587bf9915
Author: Timothy Lee <tn...@gmail.com>
AuthorDate: Mon Jun 22 13:05:49 2026 -0700
docs: restructure Burr UI documentation into dedicated section (#411) (#815)
* 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: 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 | 1 +
docs/ui/deployment.rst | 58 +++++++++++++++++++++++++++++
docs/ui/getting-started.rst | 89 +++++++++++++++++++++++++++++++++++++++++++++
docs/ui/index.rst | 50 +++++++++++++++++++++++++
docs/ui/notebook.rst | 58 +++++++++++++++++++++++++++++
5 files changed, 256 insertions(+)
diff --git a/docs/index.rst b/docs/index.rst
index b30309bc..8e3a90c8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -25,6 +25,7 @@
:caption: Apache Burr
getting_started/index
+ ui/index
examples/index
concepts/index
reference/index
diff --git a/docs/ui/deployment.rst b/docs/ui/deployment.rst
new file mode 100644
index 00000000..3d98f2a2
--- /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 00000000..b205812d
--- /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 <burr.core.application.ApplicationBuilder.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="<prior-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 00000000..2c033bd2
--- /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 00000000..5fae49d6
--- /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