Observability API Reference

This page documents the complete API for Clearstone's observability and tracing system.

TracerProvider

The entry point for the tracing system.

from clearstone.observability import TracerProvider

provider = TracerProvider(db_path="traces.db")
tracer = provider.get_tracer("my_agent", version="1.0")

clearstone.observability.provider.TracerProvider

A central provider that manages the lifecycle of the entire tracing system, including the storage backend, buffer, and individual tracers.

get_tracer(name, version='0.1.0')

Gets or creates a Tracer instance. All tracers created by this provider will share the same underlying storage and buffer.

shutdown()

Gracefully shuts down the tracing system, ensuring all buffered spans are written to storage.

Tracer

Creates and manages spans.

tracer = provider.get_tracer("my_agent")

with tracer.span("operation_name") as span:
    pass

clearstone.observability.tracer.Tracer

The primary API for creating and managing spans within a trace. Supports both integrated mode (with external buffer) and legacy mode (internal buffer).

clear_buffer()

Clears the in-memory buffer (legacy mode only).

get_buffered_spans()

Returns a copy of the current in-memory span buffer (legacy mode only).

span(name, kind=SpanKind.INTERNAL, attributes=None)

Creates a new span that is managed by a context manager.

Parameters:

Name	Type	Description	Default
name	str	A human-readable name for the operation (e.g., "agent.think").	required
kind	SpanKind	The OTel-aligned kind of the span (e.g., SpanKind.CLIENT).	INTERNAL
attributes	Optional[Dict[str, Any]]	A dictionary of initial attributes for the span.	None

Returns:

Type	Description
SpanContextManager	A SpanContextManager to be used in a 'with' statement.

Span Models

Span

Represents a single operation with timing and metadata.

with tracer.span("operation", attributes={"key": "value"}) as span:
    span.set_status("OK")

clearstone.observability.models.Span

Bases: BaseModel

The core data structure for a single traced operation, designed for high-fidelity capture and replay.

duration_ns property

Calculates the span duration in nanoseconds if the span is complete.

Trace

A complete execution flow (collection of spans).

trace = provider.trace_store.get_trace(trace_id)

print(f"Root: {trace.root_span.name}")
for span in trace.spans:
    print(f"  - {span.name}")

clearstone.observability.models.Trace

Bases: BaseModel

A collection of spans for a complete agent execution.

SpanKind

Enum defining the type of operation.

from clearstone.observability import SpanKind

with tracer.span("api_call", kind=SpanKind.CLIENT):
    pass

clearstone.observability.models.SpanKind

Bases: str, Enum

OTel-aligned span kind categorization.

TraceStore

Query and analyze stored traces.

trace_store = provider.trace_store

traces = trace_store.list_traces(limit=100)
trace = trace_store.get_trace(trace_id)

clearstone.storage.sqlite.TraceStore

Bases: BaseTraceStore

Manages the persistence of traces to a local SQLite database. This class handles database connections, schema creation, and writing data.

get_trace(trace_id)

Retrieves all spans for a given trace_id and reconstructs the Trace.

write_spans(spans)

Writes a batch of spans to the database in a single transaction. This is designed to be called by the SpanBuffer.

Storage Components

SpanBuffer

Asynchronous buffer for batching span writes.

clearstone.storage.sqlite.SpanBuffer

Bases: BaseSpanBuffer

An in-memory, thread-safe buffer for spans that flushes them to a writer periodically or when the buffer is full. This decouples span creation from the I/O of writing to disk.

add_span(span)

Add a span to the buffer. This is a non-blocking operation.

flush()

Manually trigger a flush of all buffered spans.

shutdown()

Flush any remaining spans and stop the background thread.