Skip to content

Observability

Event bus, tracing, and OpenTelemetry integration.

EventBus Protocol

EventBus

Bases: Protocol

Publish-subscribe event bus for runtime events.

subscribe 

subscribe(event_type: str, callback: Callable[..., Any]) -> str

Register a callback for event_type. Returns subscription ID.

unsubscribe 

unsubscribe(subscription_id: str) -> None

Remove a subscription by ID.

emit async 

emit(event_type: str, data: dict[str, Any]) -> None

Emit an event to all subscribers of event_type.

InMemoryEventBus

InMemoryEventBus

Default event bus -- fire-and-forget async callbacks.

Callbacks that raise exceptions are silently ignored (fire-and-forget). Supports both sync and async callbacks.

subscribe 

subscribe(event_type: str, callback: Callable[..., Any]) -> str

Register a callback for event_type. Returns unique subscription ID.

unsubscribe 

unsubscribe(subscription_id: str) -> None

Remove a subscription by ID. No-op if ID not found.

emit async 

emit(event_type: str, data: dict[str, Any]) -> None

Emit an event to all subscribers. Errors in callbacks are swallowed.

Tracer Protocol

Tracer

Bases: Protocol

Tracing interface for spans.

start_span 

start_span(name: str, attrs: dict[str, Any] | None = None) -> str

Start a new span. Returns span ID.

end_span 

end_span(span_id: str) -> None

End a span by ID.

add_event 

add_event(span_id: str, name: str, attrs: dict[str, Any] | None = None) -> None

Add an event to an existing span.

ConsoleTracer

ConsoleTracer

Simple tracer that logs spans to structlog.

Also tracks spans internally for testing/introspection.

start_span 

start_span(name: str, attrs: dict[str, Any] | None = None) -> str

Start a span and log it.

end_span 

end_span(span_id: str) -> None

End a span, log duration, and move from active to completed.

add_event 

add_event(span_id: str, name: str, attrs: dict[str, Any] | None = None) -> None

Add an event to a span.

OTelExporter

OTelExporter

Bridges Cognitia EventBus events to OpenTelemetry spans.

Follows OTel GenAI Semantic Conventions (v1.37+). Each LLM call and tool call becomes an OTel span with standard attributes.

Parameters:

Name Type Description Default
tracer_provider Any

Optional OTel TracerProvider. If None, uses the global provider.

 None
service_name str

Service name for the tracer. Default: "cognitia".

 'cognitia'
runtime_name str | None

Optional runtime identifier (e.g. "thin", "claude_code").

 None
session_id str | None

Optional session identifier for correlating spans across turns.

 None

attach 

attach(event_bus: Any = None) -> None

Subscribe to EventBus events.

Parameters:

Name Type Description Default
event_bus Any

EventBus to subscribe to. If None, uses the bus passed to the constructor.

 None

detach 

detach(event_bus: Any = None) -> None

Unsubscribe from all events and end any lingering spans.

Parameters:

Name Type Description Default
event_bus Any

EventBus to unsubscribe from. If None, uses the stored bus.

 None