Observability¶

Tracing, metrics, and a zero-dependency event hook for OpenTelemetry wiring.

Auto-generated docs

When trails is installed, run ENABLE_MKDOCSTRINGS=true ./scripts/docs-build for full docstring-extracted reference.

Event hook (observer API)¶

Symbol	Signature	Description
`register_observer`	`register_observer(callback: Callable[[str, dict], None]) -> None`	Register a callback to receive every emitted event. Observers are best-effort (exceptions caught + logged)
`unregister_observer`	`unregister_observer(callback) -> None`	Remove the first registration of a callback. No-op if not registered
`clear_observers`	`clear_observers() -> None`	Remove every registered observer (test helper)
`emit`	`emit(kind: EventKind, **fields) -> None`	Fire an event to every registered observer

EventKind is a Literal type covering these event kinds:

Event kind	Description
`"capability_started"`	Fired at the start of a capability invocation
`"capability_completed"`	Fired on successful completion
`"capability_failed"`	Fired when a capability handler raises
`"llm_call"`	Fired after each LLM completion
`"kg_write"`	Fired after KG write operations (add, save, update)
`"kg_query"`	Fired after KG read operations (query, match)

Symbol	Signature	Description
`enable_otlp`	`enable_otlp(endpoint: str \\| None = None, service_name: str = "trails") -> OTLPExporter`	Create an OTLPExporter and register it as an observer. Requires `opentelemetry-sdk`
`OTLPExporter`	`OTLPExporter(endpoint: str \\| None = None, service_name: str = "trails")`	Observer that converts Trails events into OpenTelemetry spans

Symbol	Signature	Description
`tracer`	`TrailsTracer` (module singleton)	Lightweight in-memory tracer with JSON logging
`metrics`	`TrailsMetrics` (module singleton)	In-memory metrics for capability invocations (counters + latency)
`prom_metrics`	`MetricsRegistry` (module singleton)	Prometheus-compatible metrics registry with text exposition rendering