> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/governance/observability.md). # Observability Observability is the record of what your agents actually did. Every request is captured, and the page presents that record at three levels. * A **trace** is one end-to-end invocation: what came in, what went out, how long it took, what it cost. * An **observation** is a single step inside a trace, a model call, a tool invocation, a retrieval, and observations nest, so a trace is a tree rather than a list. * A **session** groups related traces into one conversation, and exists only when a session id is set on them. Each level has its own tab, sharing the same time range, environment, and filter controls. The environment comes from what an agent tags its traces with on the Advanced step of its configuration, which is what keeps production and staging apart here. {% hint style="info" %} Observability records what an agent did. For container output from an agent, service, or database, see Logs. {% endhint %} ### Sessions, traces, and observations **Sessions** list the conversation, its duration, how many traces it holds, and what it cost. Opening one shows those traces in order, each expandable in place, so you can read a whole conversation without leaving the list. **Traces** list every invocation with its input, output, latency, tokens, cost, and a count of the observations inside it, broken out by level so a trace containing errors is visible before you open it. **Observations** list every individual step across the project, which is the level to work at when you are looking for a particular kind of call rather than a particular conversation. ### Reading a trace Opening a trace puts its observation tree on the left and whatever you select on the right. The tree is where you find out where time and cost went: each node carries its own duration, and failures are marked in place, so a broken tool call is visible without opening anything. The timeline view lays the same tree against a time axis, which is the faster way to see what ran in parallel and what was blocking.
Every node carries a type, set by whatever instrumented the call rather than chosen here. * **Span,** any unit of work with a start and an end. * **Generation,** a model call, with its prompt, completion, tokens, and cost. * **Embedding,** a vector embedding, also carrying model and cost. * **Tool,** a tool or function invocation. * **Retriever,** a data retrieval, such as a vector search. * **Agent,** a step where the model decides what to do next. * **Chain,** a sequence of linked operations. * **Evaluator,** an evaluation run. * **Guardrail,** a safety check. * **Event,** a single moment, with no duration. Generation and embedding are the two that carry model, token, and cost detail. The rest share a common shape. On the right, the selected node shows its cost and latency against the trace average, its input, output, metadata and more. Where the agent was following a routine, the Diagram panel renders that routine, so you can see the flow it was in rather than inferring it from node names. The Scores tab lists any evaluations attached to that node. ### From a trace to an improvement **Add to Datasets** turns a real interaction into a test case, carrying the input across as the input, the output as the expected output, and the metadata with it. You choose which dataset receives it. Annotate attaches a human score to whatever you are viewing. Traces can also be pushed into an annotation queue for someone else to review, one at a time or in bulk from the table, and any trace shows which queues it already belongs to. All tables export to CSV, JSON, or JSONL. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.interactive.ai/governance/observability.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.