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.

class burr.visibility.TracerFactory(
action: str,
sequence_id: int,
lifecycle_adapters: ~burr.lifecycle.internal.LifecycleAdapterSet,
_context_var: ~_contextvars.ContextVar[~burr.visibility.tracing.ActionSpan | None] = <ContextVar name='execution_context' default=None>,
)

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.

@action(reads=[...], writes=[...])
def my_action(state: State, __tracer: TracerFactory) -> tuple[dict, State]:
    context_manager: ActionSpanTracer = __tracer("my_span_name")
    with context_manager:
        ...
class burr.visibility.ActionSpanTracer(action: str, action_sequence_id: int, span_name: str, lifecycle_adapters: ~burr.lifecycle.internal.LifecycleAdapterSet, span_dependencies: ~typing.List[str], top_level_span_count: int = 0, context_var=<ContextVar name='execution_context' default=None>)

Context manager for use within tracing actions. This has the role solely of delegating to hooks – it does not do anything except manage context and pass those to the hooks.

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

@action(reads=[...], writes=[...])
def my_action(state: State, __tracer: TracerFactory) -> tuple[dict, State]:
    context_manager: ActionSpanTracer = __tracer("my_span_name")
    with context_manager:
        ...

The following hooks are respected:

  • pre_span_start and async pre_span_start

  • post_span_end and async post_span_end

class burr.visibility.ActionSpan(
action: str,
action_sequence_id: int,
name: str,
parent: Optional[ForwardRef('ActionSpan')],
sequence_id: int = 0,
child_count: int = 0,
)
classmethod create_initial(
action: str,
name: str,
sequence_id: int,
action_sequence_id: int,
) → ActionSpan

Creates the initial action span for an action. This should be only called if the current action span is none.

Parameters:

  • action

  • name

  • sequence_id

Returns: