Skip to content

armgit / burr

Public Imported from GitHub
0

Build applications that make decisions (chatbots, agents, simulations, etc...). Monitor, trace, persist, and execute on your own infrastructure.

Adds documentation for tracing

elijahbenizzy6d0f68ee118e
diff --git a/burr/lifecycle/base.py b/burr/lifecycle/base.py
index 597da771..da158596 100644
--- a/burr/lifecycle/base.py
+++ b/burr/lifecycle/base.py
@@ -117,7 +117,7 @@ class PostApplicationCreateHook(abc.ABC):
@lifecycle.base_hook("pre_start_span")
class PreStartSpanHook(abc.ABC):
"""Hook that runs before a span is started in the tracing API.
- This can be either a context manager or a logger."""
+ This can be either a context manager or a logger of sorts."""
@abc.abstractmethod
def pre_start_span(
diff --git a/burr/visibility/__init__.py b/burr/visibility/__init__.py
index 39f4c4b7..b8d7a881 100644
--- a/burr/visibility/__init__.py
+++ b/burr/visibility/__init__.py
@@ -1,4 +1,3 @@
-from burr.visibility.tracing import ActionSpan
-from burr.visibility.tracing import TracerFactory as Tracer
+from burr.visibility.tracing import ActionSpan, ActionSpanTracer, TracerFactory
-__all__ = ["Tracer", "ActionSpan"]
+__all__ = ["TracerFactory", "ActionSpan", "ActionSpanTracer"]
diff --git a/burr/visibility/tracing.py b/burr/visibility/tracing.py
index b7ddadaa..0c21ff2d 100644
--- a/burr/visibility/tracing.py
+++ b/burr/visibility/tracing.py
@@ -79,14 +79,22 @@ class ActionSpanTracer(AbstractContextManager, AbstractAsyncContextManager):
Note that a new instance of this will be passed to every action that is traced. This allows
us to reset this based on state. This can handle both synchronous and asynchronous contexts.
+ You will be using this through the action API. When you declare ``__tracer`` as a parameter,
+ it gives you a callable that, when called with a span name, returns an `ActionSpanTracer`
+ .. code-block:: python
- The following hooks are ran:
- - pre_span_start
- - post_span_end
+ @action(reads=[...], writes=[...])
+ def my_action(state: State, __tracer: TracerFactory) -> tuple[dict, State]:
+ context_manager: ActionSpanTracer = __tracer("my_span_name")
+ with context_manager:
+ ...
- And we'll likely add:
- - log_artifact
+
+ The following hooks are respected:
+
+ - :py:class:`pre_span_start <burr.lifecycle.base.PreSpanStart>` and :py:class:`async pre_span_start <burr.lifecycle.base.PreSpanStartAsync>`
+ - :py:class:`post_span_end <burr.lifecycle.base.PostSpanEnd>` and :py:class:`async post_span_end <burr.lifecycle.base.PostSpanEndAsync>`
"""
def __init__(
@@ -172,6 +180,7 @@ class ActionSpanTracer(AbstractContextManager, AbstractAsyncContextManager):
)
def __enter__(self):
+ """Enters the context manager"""
enter_context = self._enter()
self._sync_hooks_enter(enter_context)
return self
@@ -182,7 +191,7 @@ class ActionSpanTracer(AbstractContextManager, AbstractAsyncContextManager):
__exc_value: Optional[Type[BaseException]],
__traceback: Optional[Type[BaseException]],
) -> Optional[bool]:
- """Raise any exception triggered within the runtime context."""
+ """Exits the context manager."""
prior_execution_context = self._exit()
self._sync_hooks_exit(prior_execution_context)
return None
@@ -191,6 +200,7 @@ class ActionSpanTracer(AbstractContextManager, AbstractAsyncContextManager):
raise NotImplementedError
async def __aenter__(self) -> "ActionSpanTracer":
+ """Enters the context manager, async mode"""
enter_context = self._enter()
self._sync_hooks_enter(enter_context)
await self._async_hooks_enter(self.context_var.get())
@@ -202,6 +212,7 @@ class ActionSpanTracer(AbstractContextManager, AbstractAsyncContextManager):
__exc_value: Optional[Type[BaseException]],
__traceback: Optional[Type[BaseException]],
) -> Optional[bool]:
+ """Exits the context manager, async mode"""
prior_execution_context = self._exit()
self._sync_hooks_exit(prior_execution_context)
await self._async_hooks_exit(prior_execution_context)
@@ -209,6 +220,26 @@ class ActionSpanTracer(AbstractContextManager, AbstractAsyncContextManager):
class TracerFactory:
+ """Represents a tracer factory to create tracer instances. User never instantiates this
+ directly. Rather, this gets injected by the application. This gives a new span.
+
+ Note this carries state -- the top level span count. This is important for the sequence id
+ at the root level.
+
+ You will only ever see a tracer factory in the context of an action, passed through the `__tracer`
+ parameter.
+
+ .. code-block:: python
+
+ @action(reads=[...], writes=[...])
+ def my_action(state: State, __tracer: TracerFactory) -> tuple[dict, State]:
+ context_manager: ActionSpanTracer = __tracer("my_span_name")
+ with context_manager:
+ ...
+
+
+ """
+
def __init__(
self,
action: str,
@@ -216,11 +247,7 @@ class TracerFactory:
lifecycle_adapters: LifecycleAdapterSet,
_context_var: ContextVar[Optional[ActionSpan]] = execution_context_var,
):
- """Represents a tracer factory to create tracer instances. User never instantiates this
- directly. Rather, this gets injected by the application. This gives a new span.
-
- Note this carries state -- the top level span count. This is important for the sequence id
- at the root level.
+ """Instantiates a tracer factory.
:param action: Action name
:param lifecycle_adapters: Lifecycle adapters
diff --git a/docs/concepts/additional-visibility.rst b/docs/concepts/additional-visibility.rst
new file mode 100644
index 00000000..885567af
--- /dev/null
+++ b/docs/concepts/additional-visibility.rst
@@ -0,0 +1,89 @@
+=====================
+Additional Visibility
+=====================
+
+Burr comes with the ability to see inside your actions. This is a very pluggable framework
+that comes with the default tracking client.
+
+
+-------
+Tracing
+-------
+
+Burr comes with a tracing capability to see recursive spans inside an action. This is similar to
+the `OpenTelemetry <https://opentelemetry.io/>`_ sdk, although it is simplified significantly.
+
+To add the tracing capability, the action first has to declare a ``__tracer`` input. This is a
+an object that instantiates spans and tracks state.
+
+Then, using the `__tracer` as a callable, you can instantiate spans and track state.
+
+For the function-based API, this would look as follows:
+
+.. code-block:: python
+
+ from burr.visibility import TracingFactory
+ from burr.core import action
+
+ @action(reads=['input_var'], writes=['output_var'], __tracer: TracingFactory)
+ def my_action(state: State) -> Tuple[dict, State]:
+ with __tracer('process_data'):
+ initial_data = _process_data(state['input_var'])
+ with __tracer('validate_data'):
+ _validate(initial_data)
+ with __tracer('transform_data', dependencies=['process_data']):
+ transformed_data = _transform(initial_data)
+ return {'output_var': transformed_data}, state.update({'output_var': transformed_data})
+
+
+This would create the following traces:
+
+#. ``process_data``
+#. ``validate_data`` as a child of ``process_data``
+#. ``transform_data`` as a causal dependent of ``process_data``
+
+Dependencies are used to express [dag](-style structures of spans within actions. This is useful for gaining visibility into the internal structure
+of an action, but is likely best used with integrations with micro-orchestration systems for implementating actions, such as Hamilton or Lanchain.
+This maps to the `span link <https://opentelemetry.io/docs/concepts/signals/traces/#span-links>`_ concept in OpenTelemetry.
+
+Note that, on the surface, this doesn't actually *do* anything. It has to be paired with the appropriate hooks.
+These just function as callbacks (on enter/exit). The :py:class:`LocalTrackingClient <burr.tracking.LocalTrackingClient>`, used by the
+:ref:`tracking <tracking>` feature forms one of these hooks, but we will be adding more, including:
+
+1. An OpenTelemetry client
+2. A DataDog client
+
+.. note::
+
+ The class-based API can leverage this by declaring ``inputs`` as ``__tracer`` and then using the ``__tracer`` inside the ``run`` method.
+
+------------
+Observations
+------------
+
+(This is a work in progress, and is not complete)
+
+You can make observations on the state by calling out to the `log_artifact` method on the `__tracer` context manager.
+For instance:
+
+.. code-block:: python
+
+ from burr.visibility import TracingFactory
+ from burr.core import action
+
+ @action(reads=['input_var'], writes=['output_var'], __tracer: TracingFactory)
+ def my_action(state: State) -> Tuple[dict, State]:
+ with __tracer('process_data'):
+ initial_data = _process_data(state['input_var'])
+ with __tracer('validate_data'):
+ validation_results = _validate(initial_data)
+ t.log_artifact(validation_results=validation_results)
+ with __tracer('transform_data', dependencies=['process_data']) as t:
+ transformed_data = _transform(initial_data)
+ t.log_artifact(transformed_data_size=len(transformed_data))
+
+ return {'output_var': transformed_data}, state.update({'output_var': transformed_data})
+
+The output can be any "json-dumpable" object (or pydantic model). This will be stored along with the span and can be used for debugging or analysis.
+
+You can read more in the :ref:`reference documentation <visibility>`.
diff --git a/docs/concepts/hooks.rst b/docs/concepts/hooks.rst
index 3dc3f399..3708573b 100644
--- a/docs/concepts/hooks.rst
+++ b/docs/concepts/hooks.rst
@@ -35,6 +35,7 @@ We implement the pre/post run step hooks.
state: "State",
action: "Action",
result: Optional[dict],
+ sequence_id: int,
exception: Exception,
**future_kwargs: Any,
):
diff --git a/docs/concepts/index.rst b/docs/concepts/index.rst
index 838a972e..e117f0b2 100644
--- a/docs/concepts/index.rst
+++ b/docs/concepts/index.rst
@@ -15,4 +15,5 @@ Overview of the concepts -- read these to get a mental model for how Burr works.
transitions
hooks
tracking
+ additional-visibility
planned-capabilities
diff --git a/docs/concepts/planned-capabilities.rst b/docs/concepts/planned-capabilities.rst
index 5882f059..664c958d 100644
--- a/docs/concepts/planned-capabilities.rst
+++ b/docs/concepts/planned-capabilities.rst
@@ -1,5 +1,5 @@
====================
-Planned capabilities
+Planned Capabilities
====================
These are on the roadmap (and will be part of Burr in the imminent future), but have not been built yet.
@@ -109,6 +109,7 @@ One could imagine adding it as a condition (a few possibilities)
error(APIException) # infinite retries
error(APIException, max=3) # 3 visits to this edge then it gets reset if this is not chosen
# That's stored in state
+ )
)
Will have to come up with ergonomic APIs -- the above are just some ideas.
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index f6184f4b..dae21c46 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -16,5 +16,6 @@ need functionality that is not publicly exposed, please open an issue and we can
state
conditions
tracking
+ visibility
lifecycle
integrations/index
diff --git a/docs/reference/lifecycle.rst b/docs/reference/lifecycle.rst
index 7287d3b3..6d6c9dfe 100644
--- a/docs/reference/lifecycle.rst
+++ b/docs/reference/lifecycle.rst
@@ -22,6 +22,19 @@ and add instances to the application builder to customize your state machines's
.. autoclass:: burr.lifecycle.base.PostApplicationCreateHook
:members:
+.. autoclass:: burr.lifecycle.base.PreStartSpanHook
+ :members:
+
+.. autoclass:: burr.lifecycle.base.PreStartSpanHookAsync
+ :members:
+
+.. autoclass:: burr.lifecycle.base.PostEndSpanHook
+ :members:
+
+.. autoclass:: burr.lifecycle.base.PostEndSpanHookAsync
+ :members:
+
+
These hooks are available for you to use:
.. autoclass:: burr.lifecycle.default.StateAndResultsFullLogger
diff --git a/docs/reference/visibility.rst b/docs/reference/visibility.rst
new file mode 100644
index 00000000..e707ebc2
--- /dev/null
+++ b/docs/reference/visibility.rst
@@ -0,0 +1,18 @@
+.. _visibility:
+
+
+======================
+Tracing Inside Actions
+======================
+
+Tooling for gaining visibility inside actions. You will never instantiate these directly,
+they are all injected by the framework. This is purely for reference.
+
+.. autoclass:: burr.visibility.TracerFactory
+ :members:
+
+.. autoclass:: burr.visibility.ActionSpanTracer
+ :members:
+
+.. autoclass:: burr.visibility.ActionSpan
+ :members: