Tracing

configure

configure(**kwargs) -> None

Configures agent tracing using a Langfuse backend. Once configured, all agent activities, code executions and model calls are automatically captured and exported to Langfuse.

Accepts all Langfuse configuration options. Configuration options can be provided as parameters to configure() or via environment variables.

Should be called at application startup.

Parameters:

Name	Type	Description	Default
**kwargs		Langfuse configuration parameters.	{}

Source code in freeact/tracing/context.py

def configure(**kwargs) -> None:
    """Configures agent tracing using a [`Langfuse`](https://langfuse.com) backend. Once configured, all agent activities, code executions and model calls are automatically captured and exported to Langfuse.

    Accepts all [Langfuse configuration options](https://python.reference.langfuse.com/langfuse/decorators#LangfuseDecorator.configure).
    Configuration options can be provided as parameters to `configure()` or via environment variables.

    Should be called at application startup.

    Args:
        **kwargs: Langfuse configuration parameters.
    """
    global _tracer

    with _tracing_setup_lock:
        if _tracer is not None:
            logger.warning("Tracing is already configured. Call 'tracing.shutdown()' first to reconfigure.")
            return

        _tracer = LangfuseTracer(**kwargs)

        atexit.register(_shutdown_tracing)

        if threading.current_thread() is threading.main_thread():
            for sig in (signal.SIGTERM, signal.SIGHUP):
                try:
                    signal.signal(sig, _shutdown_signal_handler)
                except (ValueError, OSError):
                    pass

session

session(session_id: str | None = None) -> Iterator[str]

Context manager that creates a session scope for tracing operations.

All tracing operations within this context are associated with the specified session id.

Parameters:

Name	Type	Description	Default
session_id	str | None	Identifier for the session. A random session id is generated if not specified.	None

Source code in freeact/tracing/context.py

@contextmanager
def session(session_id: str | None = None) -> Iterator[str]:
    """Context manager that creates a session scope for tracing operations.

    All tracing operations within this context are associated with the specified session id.

    Args:
        session_id: Identifier for the session. A random session id is generated if not specified.
    """
    active_session_id = session_id or create_session_id()
    token = _active_session_id_context.set(active_session_id)
    try:
        yield active_session_id
    finally:
        _active_session_id_context.reset(token)

shutdown

shutdown() -> None

Shuts down agent tracing and flushes pending traces to the backend.

shutdown() is called automatically on application exit. For manual control, call this function explicitly.

Source code in freeact/tracing/context.py

def shutdown() -> None:
    """Shuts down agent tracing and flushes pending traces to the backend.

    `shutdown()` is called automatically on application exit. For manual control, call this function explicitly.
    """
    _shutdown_tracing()