Build applications that make decisions (chatbots, agents, simulations, etc...). Monitor, trace, persist, and execute on your own infrastructure.
Python aiburrchatbot-frameworkdagsgenerative-aigraphshacktoberfestllmopsllmsmlopspersistent-data-structurestate-machinestate-managementvisibility
Adds documentation for tracing
elijahbenizzy6d0f68ee118e
diff --git a/burr/lifecycle/base.py b/burr/lifecycle/base.pyindex 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.abstractmethoddef pre_start_span(diff --git a/burr/visibility/__init__.py b/burr/visibility/__init__.pyindex 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.pyindex 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 allowsus 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 NotImplementedErrorasync 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 adaptersdiff --git a/docs/concepts/additional-visibility.rst b/docs/concepts/additional-visibility.rstnew file mode 100644index 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.rstindex 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.rstindex 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.transitionshookstracking+ additional-visibilityplanned-capabilitiesdiff --git a/docs/concepts/planned-capabilities.rst b/docs/concepts/planned-capabilities.rstindex 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 retrieserror(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.rstindex 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 canstateconditionstracking+ visibilitylifecycleintegrations/indexdiff --git a/docs/reference/lifecycle.rst b/docs/reference/lifecycle.rstindex 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.StateAndResultsFullLoggerdiff --git a/docs/reference/visibility.rst b/docs/reference/visibility.rstnew file mode 100644index 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: