> For the complete documentation index, see [llms.txt](https://docs.helvia.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helvia.ai/observatory/interaction-logs.md). # Interaction Logs The interaction log captures every internal step a workflow runs to produce an agent reply, from model calls to HTTP requests. Which steps run for any given reply depends on the workflow itself. The log is the raw record of what actually happened, and the starting point for any serious debugging or performance work. You meet the interaction log in two places: * **Observatory > Interaction Logs:** every interaction across every session, in one filterable table * **Observatory > Sessions > Chat Sessions:** open any session and select a user message to see the trace behind it, scoped to that single conversation event ### What Is an Interaction An interaction is a single atomic step your workflow runs while producing a reply. Each type of step corresponds to a node in Designer that can fire during a workflow execution. Which types appear in any given trace depends on the workflow's design.

Title	Description
LLM	A call to a language model. Captures the model, prompt, conversation history, and the model's reply
Search	A semantic search against your knowledge base. Captures the (possibly rewritten) query and the matched documents
HTTP	An outbound HTTP request to an external system. Captures the URL, method, headers, request body, and the response
Variable	A write to a variable. Captures the variable name and the value the step set
Tags	A tag operation on the session. Captures the tag or tags the step applied
Redirect	A jump to another workflow. Captures the target workflow, including the variable template used to resolve it

Regardless of type, every interaction in the log carries the same surrounding metadata:

Field	What it captures
Timestamp	When the step ran, to the millisecond
Duration	How long the step took, in milliseconds
Errors	Whether the step succeeded or failed
Source node	The friendly name of the Designer node that triggered the step
Agent	The agent that owns the workflow
Deployment	The deployment that served the session
Session ID	A unique identifier of the parent conversation
Event ID	A unique identifier shared by all steps of a single user turn
JSON Payload	The raw request and response data, shaped to fit the step's type

#### Sessions, Events, and Interactions Interactions sit at the bottom of a three-tier nesting: a session is one conversation, an event is one workflow execution within that session (typically one user turn), and an interaction is one step within an event. ```mermaid flowchart TD S["Session"] E1["Event"] Edots["..."] E2["Event"] I1["Interaction"] I1dots["..."] I2["Interaction"] I3["Interaction"] I3dots["..."] I4["Interaction"] S --> E1 S --> Edots S --> E2 E1 --> I1 E1 --> I1dots E1 --> I2 E2 --> I3 E2 --> I3dots E2 --> I4 style S fill:#615DEC,color:#fff,stroke:#615DEC style E1 fill:#615DEC,color:#fff,stroke:#615DEC style Edots fill:none,stroke:none,color:#615DEC style E2 fill:#615DEC,color:#fff,stroke:#615DEC style I1 fill:#F3A702,color:#fff,stroke:#F3A702 style I1dots fill:none,stroke:none,color:#F3A702 style I2 fill:#F3A702,color:#fff,stroke:#F3A702 style I3 fill:#F3A702,color:#fff,stroke:#F3A702 style I3dots fill:none,stroke:none,color:#F3A702 style I4 fill:#F3A702,color:#fff,stroke:#F3A702 ``` ### Exploring the Interaction Logs The Interaction Logs page at **Observatory > Interaction Logs** brings every interaction your agents have produced into one filterable table. Each row is one step a workflow ran, and selecting it opens the details in the side panel.

#### Filtering and Search Interaction Logs scopes to the typical Observatory filters. Check them first if an interaction you expect is missing. ***

		Cover image
Date Range	Set a start and end date to define the time window. Click Apply to update the results	/files/YGZDrhzwxahrZUDgDeub
Agents	Filter by agent or a specific deployment. Selected agents pin to the top of the dropdown	/files/x72II7mqcgDJkQE3RbP7
Tags	Include or exclude sessions by tag	/files/wEH8OZwrYajS6huOVqaX

{% hint style="info" %} Filters live in the URL, so sharing or bookmarking the page reproduces the same view. Your selection also persists as you navigate across the Observatory. {% endhint %} *** Use the search bar to find an interaction by the reference you have on hand: | Search by | When to use | | -------------- | ----------------------------------------------------------------------------------------------------------------- | | **Session ID** | You already have a session reference from a link, screenshot, or bug report | | **Name** | You know the node or variable label (for example, `csatSurveys`) and want every step that touched it | | **Event ID** | You have an event ID for a single workflow execution (typically one user turn) and want every step that ran in it | ### Inspecting a Single Interaction Select any interaction to open its details. This is where everything you have seen so far comes together: the interaction type, the event hierarchy, the raw payload, and more.

From any opened interaction you can:

Title	Description
Read the Payload	The raw request and response of the step in JSON, shaped to fit the interaction's type
Inspect Variables	A snapshot of session-scoped variables after this step ran, including any writes the interaction itself made
Reference the Step	The Session ID and Event ID for the step, each with a copy icon for use in tickets, reports, or the search bar on this page
View in Session	Jump back into the full conversation transcript with the user message that triggered this step already selected

#### View in Session **View in Session** is the link from a single step back to the conversation that produced it. An interaction tells you what the workflow did, but not why it had to. The session view gives you that context: the user message that triggered the step, what came before, and what came after.

Use it whenever you have found a problematic step and need the conversation around it to judge whether the behavior makes sense. See [Inside a Session](/observatory/inside-a-session.md) for what you land on. ### Logs in a Chat Session When you want to debug one specific conversation, start in **Observatory > Sessions > Chat Sessions**. Select the session, then select a user message in the transcript to see the workflow steps that ran in response to it. All the same interaction concepts apply here, just at a narrower scope: one user message at a time.

A few things to know about this view: * Each user message is the trigger that starts a workflow execution. Selecting a user message shows the steps that produced just that one reply. * The first agent message is the exception. Select it directly, because it runs before any user input and is not tied to one. * Expand any step in the trace to drill into its full details, including the raw payload * The **Variable Values** tab shows a snapshot of session-scoped variables at this point in the conversation, including the writes that happened up through this turn {% hint style="info" %} To see every step of an entire session at once, use the Interaction Logs page with a Session ID filter instead. {% endhint %} ### Working with the Logs A handful of patterns cover most real debugging work. Each one starts from a different reference point and lands you on the relevant interaction in a few clicks. #### Investigate One Session in a Single Table When you already know the session you want to debug, the Interaction Logs page is often faster than the per-session view. Filtering by Session ID turns the table into the full chronological trace for that conversation. Every step visible at once, instead of one-message-at-a-time. 1. Copy the session ID from the per-session URL or from the **Session Details** sidebar tab inside the conversation 2. Open **Observatory > Interaction Logs** and switch the search mode to **Search by Session ID** 3. Paste the ID and run the search 4. Sort by **Timestamp**, scan for errors or long durations, and select any row to inspect its payload #### Find Slow Steps for a Specific Deployment Performance investigations often start as "responses feel slow on Webchat lately" and end at a single LLM call or external request that crosses your latency budget. Combining the Agents filter with the Long duration preset narrows the table to the steps that matter. 1. Set the **Agents** filter to the agent and deployment under investigation 2. Open the **Duration** column filter and pick **Long (>2s)** 3. Sort by **Duration** descending 4. Open the slowest rows to see exactly what each one was doing #### Triage Errors Across Agents An error count spikes on a dashboard, or a teammate flags an issue without naming a session. The Errors filter surfaces every failing step in your time window. Pattern-spotting across that subset is usually how you find the root cause. 1. Set the date range to cover the period of interest 2. Open the **Errors** column filter and pick **Yes** 3. Scan the table for patterns: a single agent, a single deployment, a single Type, or a single source node showing up repeatedly 4. Open a matching row to read the error in the payload, then use **View in Session** to see the conversation around each failure #### Find Every Step a Specific Node Produced The **Name** column shows the friendly name of the Designer node that produced each step. Setting clear, descriptive names in Designer is what makes this search useful later: the Name search is only as good as the names you assign. 1. In Designer, give each node that shows up in the interaction log a meaningful name (for example, **Knowledge Search: Pricing**) 2. In Interaction Logs, switch the search mode to **Search by Name** 3. Enter the node name to filter the table to every step that node has produced across all sessions and agents {% hint style="warning" %} **Name your nodes early:** Renaming a node later does not relabel the interactions it has already emitted. {% endhint %} ### Best Practices * **Start from the failing step, not the response text:** The trace tells you what the workflow actually did. The response is only the consequence. * **Triage globally with Errors > Yes:** When you do not yet know which session is affected, filter the view by errors and scan across agents and deployments * **Paste an Event ID to pull a whole turn:** When a bug report or log line gives you an event ID, the search returns every step that ran in that one workflow execution * **Pivot back with View in Session:** Once you have identified the problematic step, drop back into the conversation to see what the user saw and what came next {% hint style="success" %} You can now trace every step your workflows execute, both inside a single session and across all of them, and use the filters, search, and JSON payloads to debug agent behavior end to end. {% endhint %} --- # 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.helvia.ai/observatory/interaction-logs.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.

:robot:

LLM

:book-blank:

Search

:globe:

HTTP

:brackets-curly:

Variable

:tags:

Tags

:shuffle:

Redirect

:calendar:

Date Range

:robot:

Agents

:tags:

Tags

:code:

Read the Payload

:brackets-curly:

Inspect Variables

:fingerprint:

Reference the Step

:share-from-square:

View in Session