Skip to content

Tracer Registry API Reference

Registry pattern for tracing providers with support for NoOp, Logfire, Langfuse, and Opik backends.

from axion._core.tracing.registry import TracerRegistry, BaseTracer, BaseSpan
from axion._core.tracing.noop.tracer import NoOpTracer
from axion._core.tracing.logfire.tracer import LogfireTracer
from axion._core.tracing.langfuse.tracer import LangfuseTracer
from axion._core.tracing.opik.tracer import OpikTracer
N

NoOpTracer

Zero-overhead tracer for tests and production when observability is not needed.

L

LogfireTracer

OpenTelemetry-based observability with Logfire integration for detailed span tracing.

F

LangfuseTracer

LLM-specific observability with cost tracking, prompt management, and evaluation logging.

O

OpikTracer

Comet Opik integration for experiment tracking, LLM call logging, and evaluation traces.

TracerRegistry

axion._core.tracing.registry.TracerRegistry

Registry for tracer implementations using decorator pattern.

This class provides a simple way to register and retrieve tracer implementations by name, following the same pattern as LLMRegistry.

Example

@TracerRegistry.register('my_tracer') class MyTracer(BaseTracer): ...

Later, retrieve the tracer class

TracerClass = TracerRegistry.get('my_tracer') tracer = TracerClass.create(metadata_type='llm')

register classmethod 

register(name: str) -> Callable[[Type[BaseTracer]], Type[BaseTracer]]

Decorator to register a tracer implementation.

Parameters:

  • name (str) –

    The name to register the tracer under (e.g., 'noop', 'logfire', 'langfuse')

Returns:

Example

@TracerRegistry.register('custom') class CustomTracer(BaseTracer): ...

get classmethod 

get(name: str) -> Type[BaseTracer]

Get a tracer class by name.

Parameters:

  • name (str) –

    The registered name of the tracer

Returns:

Raises:

  • ValueError –

    If the tracer is not registered

list_providers classmethod 

list_providers() -> List[str]

List all registered tracer provider names.

Returns:

  • List[str] –

    List of registered tracer names

is_registered classmethod 

is_registered(name: str) -> bool

Check if a tracer is registered.

Parameters:

  • name (str) –

    The name to check

Returns:

  • bool –

    True if registered, False otherwise

display classmethod 

display() -> None

Display the tracer registry in a rich HTML format.

BaseTracer

axion._core.tracing.registry.BaseTracer

Bases: ABC

Abstract base class for all tracer implementations.

This defines the core interface that all tracers (NoOp, Logfire, Langfuse, etc.) must implement. Users can create custom tracers by subclassing this and registering with @TracerRegistry.register('name').

Example

@TracerRegistry.register('my_custom_tracer') class MyCustomTracer(BaseTracer): # implement abstract methods ...

create abstractmethod classmethod 

create(metadata_type: str = 'default', tool_metadata: Optional[Any] = None, **kwargs) -> BaseTracer

Factory method to create tracer instances.

Parameters:

  • metadata_type (str, default: 'default' ) –

    Type of metadata (e.g., 'llm', 'knowledge', 'evaluation')

  • tool_metadata (Optional[Any], default: None ) –

    Optional metadata about the tool being traced

  • **kwargs –

    Additional implementation-specific arguments

Returns:

span abstractmethod 

span(operation_name: str, **attributes)

Create a synchronous span context manager.

Parameters:

  • operation_name (str) –

    Name of the operation being traced

  • **attributes –

    Additional attributes to attach to the span

Yields:

  • –

    A span object that can be used to add attributes or events

async_span abstractmethod async 

async_span(operation_name: str, **attributes)

Create an asynchronous span context manager.

Parameters:

  • operation_name (str) –

    Name of the operation being traced

  • **attributes –

    Additional attributes to attach to the span

Yields:

  • –

    A span object that can be used to add attributes or events

start abstractmethod 

start(**attributes) -> None

Start execution tracking.

complete abstractmethod 

complete(output_data: Optional[Dict[str, Any]] = None, **attributes) -> None

Complete execution tracking.

fail abstractmethod 

fail(error: str, **attributes) -> None

Handle execution failure.

add_trace abstractmethod 

add_trace(event_type: str, message: str, metadata: Optional[Dict[str, Any]] = None) -> None

Add a trace event.

flush 

flush() -> None

Flush any pending traces to the backend.

Override in implementations that buffer traces (e.g., Langfuse). Default implementation is a no-op.

shutdown 

shutdown() -> None

Gracefully shutdown the tracer.

Override in implementations that need cleanup. Default implementation calls flush().

info 

info(msg: Any) -> None

Log info message.

BaseSpan

axion._core.tracing.registry.BaseSpan

Bases: Protocol

Protocol defining the standard interface for all span implementations.

All provider spans (NoOp, Logfire, Langfuse, Opik) implement this interface, enabling type-safe span handling without provider-specific isinstance checks.

Built-in Tracers

NoOpTracer

axion._core.tracing.noop.tracer.NoOpTracer 

NoOpTracer(metadata_type: str, tool_metadata: Optional[ToolMetadata] = None, enable_logfire: bool = False, trace_id: Optional[str] = None, **kwargs)

Bases: BaseTracer

A no-operation tracer that mirrors the LogfireTracer interface.

This class provides a complete, non-functional implementation of the tracer so that it can be swapped with the real LogfireTracer without causing any errors. All tracing and logging methods are designed to do nothing, ensuring minimal performance overhead when tracing is disabled.

create classmethod 

create(metadata_type: str, tool_metadata: Optional[ToolMetadata] = None, enable_logfire: bool = False, **kwargs) -> NoOpTracer

Factory method to create a NoOpTracer instance.

span 

span(operation_name: str, **attributes)

Creates a synchronous span AND sets the tracer context for its duration. Uses shared context management from main tracer module.

async_span async 

async_span(operation_name: str, **attributes)

Creates an asynchronous span AND sets the tracer context for its duration. Uses shared context management from main tracer module.

LogfireTracer

axion._core.tracing.logfire.tracer.LogfireTracer 

LogfireTracer(metadata_type: str, tool_metadata: Optional[ToolMetadata] = None, enable_logfire: bool = True, trace_id: Optional[str] = None, **kwargs)

Bases: BaseTracer

Tracer that combines tracing, logging, and metadata collection. Uses composition with a logger instance instead of inheritance.

create classmethod 

create(metadata_type: str, tool_metadata: Optional[ToolMetadata] = None, **kwargs) -> LogfireTracer

Factory method to create a LogfireTracer.

span 

span(operation_name: str, **attributes)

Creates a synchronous span AND sets the tracer context for its duration. Uses shared context management from main tracer module.

async_span async 

async_span(operation_name: str, **attributes)

Creates an asynchronous span AND sets the tracer context for its duration. Uses shared context management from main tracer module.

log_llm_call 

log_llm_call(model: str, prompt: str, response: str, prompt_tokens: int = None, completion_tokens: int = None, latency: float = None, cost_estimate: float = None, error: str = None, **attributes) -> None

Log an LLM call with automatic tracing.

log_retrieval_call 

log_retrieval_call(context: List[Dict[str, Any]], latency: float, query: str = None, **attributes) -> None

Log a retrieval call with automatic tracing.

log_evaluation 

log_evaluation(evaluation_id: str, evaluator_name: str, evaluator_type: str, dataset_size: int, latency: float, overall_metrics: List[EvaluationMetric] = None, datapoint_results: List[EvaluationDatapoint] = None, dataset_name: str = None, cost_estimate: float = None, tokens_used: int = None, error: str = None, evaluator_config: Dict[str, Any] = None, **attributes) -> None

Log an evaluation run with automatic tracing.

log_database_query 

log_database_query(query: str, latency: float, rows_affected: int = 0, **attributes) -> None

Log a database query with automatic tracing.

get_statistics 

get_statistics() -> Dict[str, Any]

Get statistics from metadata.

display_statistics 

display_statistics()

Display statistics using the display utility.

LangfuseTracer

axion._core.tracing.langfuse.tracer.LangfuseTracer 

LangfuseTracer(metadata_type: str = 'default', tool_metadata: Optional[ToolMetadata] = None, public_key: Optional[str] = None, secret_key: Optional[str] = None, base_url: Optional[str] = None, trace_id: Optional[str] = None, tags: Optional[List[str]] = None, environment: Optional[str] = None, session_id: Optional[str] = None, user_id: Optional[str] = None, **kwargs)

Bases: BaseTracer

Langfuse-based tracer for LLM observability.

This tracer integrates with Langfuse (https://langfuse.com) to provide detailed tracing and observability for LLM applications.

Configuration

Set the following environment variables or pass to constructor: - LANGFUSE_PUBLIC_KEY: Your Langfuse public key - LANGFUSE_SECRET_KEY: Your Langfuse secret key - LANGFUSE_BASE_URL: API endpoint (default: https://cloud.langfuse.com) - LANGFUSE_TAGS: Comma-separated list of tags (e.g., "prod,v1.0") - LANGFUSE_ENVIRONMENT: Environment name (e.g., "production", "staging")

Example

from axion._core.tracing import Tracer, configure_tracing

Configure via environment

os.environ['TRACING_MODE'] = 'langfuse' os.environ['LANGFUSE_PUBLIC_KEY'] = 'pk-lf-...' os.environ['LANGFUSE_SECRET_KEY'] = 'sk-lf-...' os.environ['LANGFUSE_TAGS'] = 'prod,v1.0' os.environ['LANGFUSE_ENVIRONMENT'] = 'production'

configure_tracing() tracer = Tracer('llm') with tracer.span('my-operation', tags=['custom-tag']): # ... your code tracer.flush()

Or pass tags/environment directly:

tracer = LangfuseTracer(tags=['prod', 'v1.0'], environment='production') with tracer.span('my-operation'): # ... your code

create classmethod 

create(metadata_type: str = 'default', tool_metadata: Optional[ToolMetadata] = None, **kwargs) -> LangfuseTracer

Factory method to create a LangfuseTracer instance.

span 

span(operation_name: str, **attributes)

Creates a synchronous span AND sets the tracer context for its duration.

Parameters:

  • operation_name (str) –

    Name of the operation being traced

  • **attributes –

    Additional attributes to attach to the span

Yields:

  • –

    A LangfuseSpan object

async_span async 

async_span(operation_name: str, **attributes)

Creates an asynchronous span AND sets the tracer context for its duration.

Parameters:

  • operation_name (str) –

    Name of the operation being traced

  • **attributes –

    Additional attributes to attach to the span

Yields:

  • –

    A LangfuseSpan object

flush 

flush() -> None

Flush pending traces to Langfuse.

log_llm_call 

log_llm_call(*args, **kwargs) -> None

Log an LLM call to Langfuse.

Prefer attaching prompt/response/usage to the current span rather than creating a separate generation observation, to avoid duplicates in the Langfuse UI.

log_evaluation 

log_evaluation(*args, **kwargs) -> None

Log an evaluation.

OpikTracer

axion._core.tracing.opik.tracer.OpikTracer 

OpikTracer(metadata_type: str = 'default', tool_metadata: Optional[ToolMetadata] = None, api_key: Optional[str] = None, workspace: Optional[str] = None, project_name: Optional[str] = None, base_url: Optional[str] = None, trace_id: Optional[str] = None, **kwargs)

Bases: BaseTracer

Opik-based tracer for LLM observability.

This tracer integrates with Opik (https://www.comet.com/docs/opik/) to provide detailed tracing and observability for LLM applications.

Configuration

Set the following environment variables or pass to constructor: - OPIK_API_KEY: Your Opik API key - OPIK_WORKSPACE: Your workspace name - OPIK_PROJECT_NAME: Project name (default: 'axion') - OPIK_URL_OVERRIDE: API endpoint (default: https://www.comet.com/opik/api)

Example

from axion._core.tracing import Tracer, configure_tracing

Configure via environment

os.environ['TRACING_MODE'] = 'opik' os.environ['OPIK_API_KEY'] = 'your-api-key' os.environ['OPIK_WORKSPACE'] = 'your-workspace'

configure_tracing() tracer = Tracer('llm') with tracer.span('my-operation'): # ... your code tracer.flush()

create classmethod 

create(metadata_type: str = 'default', tool_metadata: Optional[ToolMetadata] = None, **kwargs) -> OpikTracer

Factory method to create an OpikTracer instance.

span 

span(operation_name: str, **attributes)

Creates a synchronous span AND sets the tracer context for its duration.

Parameters:

  • operation_name (str) –

    Name of the operation being traced

  • **attributes –

    Additional attributes to attach to the span

Yields:

  • –

    An OpikSpan object

async_span async 

async_span(operation_name: str, **attributes)

Creates an asynchronous span AND sets the tracer context for its duration.

Parameters:

  • operation_name (str) –

    Name of the operation being traced

  • **attributes –

    Additional attributes to attach to the span

Yields:

  • –

    An OpikSpan object

flush 

flush() -> None

Flush pending traces to Opik.

shutdown 

shutdown() -> None

Gracefully shutdown the tracer.

log_llm_call 

log_llm_call(*args, **kwargs) -> None

Log an LLM call to Opik as a generation span.

log_evaluation 

log_evaluation(*args, **kwargs) -> None

Log an evaluation to Opik.

Tracing Deep Dive Langfuse Guide