diff --git a/docs/index.rst b/docs/index.rst index b30309bc7..8e3a90c8a 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 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