docs

Observability

The SDK provides multiple layers of observability — from quick debug output to full OpenTelemetry tracing and custom event streaming via the EventBus.

Quick debug mode

Enable debug mode to see every event (tool calls, LLM responses, token counts) printed to stderr:

Python
from ninetrix import Agent, enable_debug

agent = Agent(name="assistant", provider="anthropic", model="claude-sonnet-4-6")
enable_debug(agent)   # or enable_debug() for all agents

result = agent.run("What is MCP?")
# stderr shows: [tool_start] search_web("MCP protocol") ...
#               [tool_end] search_web → 3 results
#               [token] The Model Context Protocol...
#               [done] 342 tokens, $0.0041

OpenTelemetry

Export traces to any OpenTelemetry-compatible backend (Jaeger, Grafana Tempo, Datadog, etc.):

Python
from ninetrix import configure_otel

# Requires: pip install ninetrix-sdk[otel]
configure_otel(
    endpoint="http://localhost:4317",    # OTLP gRPC endpoint
    service_name="my-agent-app",
)

# All agent runs are now traced automatically
# Each tool call, LLM turn, and checkpoint is a span

EventBus

Subscribe to agent lifecycle events programmatically for custom logging, metrics, or alerting:

Python
from ninetrix import EventBus, AgentEvent

bus = EventBus()

@bus.on("tool_end")
def on_tool_end(event: AgentEvent):
    print(f"Tool {event.tool_name} took {event.duration_ms}ms")

@bus.on("done")
def on_done(event: AgentEvent):
    if event.cost_usd > 0.10:
        alert(f"Expensive run: ${event.cost_usd:.2f}")

RunnerReporter

Automatically report events to the Ninetrix dashboard (local or cloud):

Python
from ninetrix import RunnerReporter

# Events sent to the dashboard at this URL
reporter = RunnerReporter(
    api_url="http://localhost:8000",
    token="your-runner-token",
)

# Attach to agent — checkpoints appear in the dashboard automatically
agent = Agent(..., reporter=reporter)
On this page