Observability

Monitor agent performance, inspect execution traces, analyze token usage, and build custom dashboards to debug and optimize your agents.

Overview

Every agent execution in Connic is recorded as a run. Each run captures the full lifecycle of a request: the input that triggered it, every intermediate step the agent took, the final output, token consumption, cost estimates, and timing data. Connic provides three layers of observability to help you understand and debug your agents:

Run Logs

The Logs tab in your project shows a chronological list of all agent runs. Each row displays the run status, agent name, deployment, duration, token count with estimated cost, and when it was queued. The table updates every few seconds.

Inspecting a Run

Click any run in the logs table to open its detail view. The run detail provides the full picture of what happened during that execution.

You can also re-run any execution from the run detail view. This triggers the same agent with the same input, letting you verify that a fix resolved the issue. For queued or running runs, a cancel button is available.

Execution Traces

Execution traces provide a step-by-step breakdown of everything that happened during a run. Connic captures traces using OpenTelemetry spans, organized in a hierarchical tree structure. Each span represents a discrete operation: an LLM call, a tool invocation, a middleware hook, or a sub-agent execution.

Token Usage & Cost

Every run records detailed token consumption broken down into four categories. Understanding these categories helps you optimize cost and identify unexpected behavior.

Token counts and estimated costs are visible in multiple places:

• The runs table shows total tokens and estimated cost per run
• The run detail header shows total tokens with a tooltip breaking down all four categories plus cost
• The agent detail page shows aggregate token usage for that agent
• Observability dashboards provide token charts and stat cards with configurable breakdowns

Custom Dashboards

The Observability tab in your project provides customizable dashboards for monitoring agent performance over time. You can create multiple dashboards, each with a mix of widget types arranged in a drag-and-drop grid.

Logging from Custom Code

Anything you print or log from inside a tool, middleware, hook, or guardrail is captured per run and shown in two places: the Logs tab in your project (filterable by level and source across all runs) and the run detail view (scoped to that single run). You don't need to import a Connic-specific logger. Connic attaches to Python's stdout, stderr, and the standard logging module for you.

"""A custom tool that emits logs Connic will surface in the dashboard."""
import logging
import sys
from typing import Any, Dict

log = logging.getLogger(__name__)  # -> "tools.lookup_customer"

async def lookup_customer(args: Dict[str, Any], context: Dict[str, Any]) -> Dict[str, Any]:
    customer_id = args["customer_id"]

    # Plain print -> captured as an info-level log line
    print(f"Looking up customer {customer_id}")

    # stdlib logging -> captured at the level you called
    log.warning("cache miss for %s", customer_id)

    try:
        record = await fetch_from_crm(customer_id)
    except Exception:
        # Writes to stderr -> captured as an error-level log line
        print(f"CRM lookup failed for {customer_id}", file=sys.stderr)
        raise

    return record

Agent-Level Observability

Each agent has its own detail page accessible from the Agents tab. This provides a focused view of that agent's performance:

• Statistics: Total runs, success rate with trend indicator, average duration, and total tokens used
• Status breakdown: Counts for completed, failed, running, and queued runs
• Configuration: Agent type, model, max concurrent runs, and linked tools or agents
• Run history: An agent-scoped runs table with the same filtering capabilities as the main logs page
• Manual trigger: Send a test payload to the agent directly from the dashboard

Debugging an Agent

When an agent occasionally produces incorrect results, the goal is to narrow the issue to a specific slice of runs, compare a bad run against a similar good run, and identify the first step where the execution diverges. In Connic, the fastest workflow is to isolate the pattern in Logs, compare traces side by side, inspect the decision path in LLM and tool spans, then use token patterns to confirm the likely cause.

from typing import Any, Dict

async def before(content: Dict[str, Any], context: Dict[str, Any]) -> Dict[str, Any]:
    payload = context.get("payload", {})
    context["request_type"] = "invoice_validation"
    context["customer_tier"] = payload.get("customer_tier", "unknown")
    context["workflow_version"] = "2026-03-debug-pass"
    context["debug_bucket"] = "high-risk"
    return content

Configuration for Better Observability

These agent configuration options directly impact what data is captured in traces:

Accessing Run Data in Code

The middleware after() hook is the way to programmatically access run data such as token usage and duration. The context dict passed to after() includes system fields that are populated when the agent finishes:

Use these fields to send run data to your own monitoring or analytics system:

import httpx
from typing import Any, Dict

async def after(response: str, context: Dict[str, Any]) -> str:
    """Send run metadata to an external monitoring system."""
    try:
        async with httpx.AsyncClient() as client:
            await client.post(
                "https://monitoring.internal/events",
                json={
                    "run_id": context.get("run_id"),
                    "agent": context.get("agent_name"),
                    "duration_ms": context.get("duration_ms"),
                    "tokens": context.get("token_usage", {}),
                    "request_type": context.get("request_type"),
                }
            )
    except Exception:
        pass
    return response