> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamkap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Observability

> Monitor Streamkap streaming agents with execution traces, tool-call sessions, and runtime logs, and inspect topic data with the query playground

The **Observability** tab is the single place to see what your agents are doing: per-record execution traces, tool-call activity, and runtime logs. Select an entity in the left sidebar (a streaming agent, an external agent, or a knowledge base), pick a time range, and choose what to show.

Viewing traces and tool calls requires `read:agents`; viewing **logs** requires `write:agents`.

## Entity Sidebar

The sidebar groups activity into **Streamkap Agents**, **External Agents**, and **Knowledge Bases**, plus an **All activity** view. **External Agents** are external AI assistants calling your Streamkap MCP server (see [Agents](/agents)). They show up here even though they aren't streaming agents. Each agent row shows a status dot and its 24-hour tool-call count:

* **Red** — errors in the last 24 hours
* **Green** — healthy, with recent activity
* **Grey** — idle for over an hour

Only entities active in the selected time range appear — widen the range to see more.

## Trace

The trace view shows per-record execution. Each input record produces one or more **iterations**, and each iteration lists its operations:

* **LLM** — a model call
* **Tool** — a tool invocation
* **Output** — the record written to the output topic

Each operation shows its type, status (**Success**, **Error**, or **Denied** — a tool call blocked by the agent's tool scope), and duration. Use it to see exactly how a record was processed and where a failure occurred.

## Tool Calls

The tool-call view covers **MCP** tool calls (Streamkap MCP and external MCP), grouped into **sessions** with a status histogram and per-session p95 latency. Click a span to open its detail — the tool name, timing, parameters, and any error or denial. To trace HTTP or Script tool calls, use the **Trace** view above and the agent's **Logs**.

## Logs

The log view tails the agent's runtime logs. Filter by **level** (DEBUG, INFO, WARN, ERROR) and **search** for a substring, click a histogram bar to narrow the window, or enable **Live tail** to follow new lines.

<Warning>
  Logs require the `write:agents` permission because log lines can contain record payloads.
</Warning>

<Note>
  Log lines are scoped to the shared runtime, so an agent's logs may include lines from your other agents on the same infrastructure (never another organization's). A banner flags this where it applies.
</Note>

## Query Playground

The **Query Playground** tab runs ad-hoc SQL over your Kafka topics — useful for inspecting an input topic's shape and sample records before you build an agent, or checking an output topic afterward.

Pick a topic from the tree to insert a starter query, edit the SQL, and **Run Query**. Results show the matched rows and query metadata (topic, records scanned, records matched). It requires `read:agents` and `read:topics`.

## Related

* [Manage Agents](/streaming-agents-manage) — lifecycle and the dead-letter topic
* [Observability](/observability) — system health and lineage for sources, destinations, and transforms
* [Logs](/logs) — connector and pipeline logs
* [Topics](/topics) — browse Kafka topics