# Trace Explorer

{% hint style="info" %}
Trace Explorer is in **Public Preview**. See [Feature Maturity Definitions](/reference/feature-maturity-definitions.md#public-preview) for what this means.
{% endhint %}

### Overview

Trace Explorer is a spans-first exploration surface for GenAI applications. It gives you a paginated, filterable, searchable view of every span ingested into a single application — useful for debugging individual requests, investigating evaluator failures, drilling into latency outliers, and validating instrumentation.

Open the **Trace Explorer** tab on any GenAI Application Details page.

### Concepts

| Term           | Meaning                                                                                                                                                                                                                                        |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Span**       | A single unit of work in your application — an LLM call, a tool invocation, an agent step, or a chain step. The Trace Explorer grid is one row per span.                                                                                       |
| **Trace**      | A collection of spans that share a `trace_id` and represent one end-to-end request through your application.                                                                                                                                   |
| **Session**    | A higher-level grouping (typically a multi-turn conversation) identified by a `session_id`. A session may contain multiple traces.                                                                                                             |
| **Time range** | Mandatory. Trace Explorer always filters by a time window. The UI defaults to the last 7 calendar days (ending at end-of-day UTC). The time range is enforced server-side to keep queries fast against the underlying ClickHouse partitioning. |

***

### Using the UI

#### Where it lives

Open any GenAI Application Details page, then select the **Trace Explorer** tab.

#### The DataGrid

Each row in the grid is a span. The grid is server-side paginated and sorted, with rich column controls.

**Columns visible by default**

| Column      | Notes                                                                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Type        | Span type — typically one of `llm`, `tool`, `agent`, `chain`                                                                               |
| Name        | Span operation name                                                                                                                        |
| Input       | LLM or tool input content. Query via the search bar with the **Input** scope selector (see [Searching in the UI](#searching-in-the-ui)).   |
| Output      | LLM or tool output content. Query via the search bar with the **Output** scope selector (see [Searching in the UI](#searching-in-the-ui)). |
| Timestamp   | When the span started                                                                                                                      |
| Duration    | Span duration (displayed in human-friendly units)                                                                                          |
| Status      | OpenTelemetry status code (`Ok`, `Error`, `Unset`)                                                                                         |
| **Actions** | Pinned to the right of the grid; always visible. Contains the **View Trace** icon.                                                         |

**Columns hidden by default**

These columns are available via the column picker but are not shown out of the box:

* Session ID
* Trace ID
* Span ID
* Agent
* Agent ID

**Dynamic columns**

Trace Explorer adds columns automatically based on your application's schema:

* **Evaluator output columns** — one column per output of every evaluator rule configured for the application.
* **User-defined span attribute columns** — one column per attribute you've instrumented (for example, `user_id`, `model_version`, `environment`).
* **Token count columns** — `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.usage.total_tokens`.

See [Span and Resource Attributes](https://github.com/fiddler-labs/fiddler/blob/release/26.10/docs/integrations/agentic-ai/attributes.md) for the full attribute catalog and naming conventions.

#### Filtering in the UI

Open the filter panel from any filterable column header, or from the toolbar. Filters are applied server-side. By default, filter rules are combined with **AND**; the MUI filter panel also lets you switch to **OR** within a single column.

* **ID columns** (`Session ID`, `Trace ID`, `Span ID`) — `equals` only in the UI (enable the column via the column picker first; these are hidden by default).
* **String columns** (Name, Agent, span attributes) — `is`, `is not`, `is any of` (autocomplete) or `equals` / `does not equal` (free text), depending on whether the field has a known value set.
* **Numeric columns** (Duration, token counts, numeric attributes) — `=`, `!=`, `>`, `>=`, `<`, `<=`.
* **Enum columns** (Type, Status) — single- or multi-select.
* **Boolean evaluator outputs** — `is` or `is not` with values `true` or `false`.

#### Searching in the UI

Use the search bar at the top of the grid to run a case-insensitive substring match against prompt and response content captured on your spans.

| Setting    | Detail                                                                                          |
| ---------- | ----------------------------------------------------------------------------------------------- |
| **Length** | 3 to 64 characters                                                                              |
| **Match**  | Case-insensitive substring                                                                      |
| **Index**  | Backed by a dedicated content table with n-gram and token bloom-filter indexes for fast lookups |

The **scope selector** next to the search bar restricts which content fields are searched:

| Scope             | Searches                                       |
| ----------------- | ---------------------------------------------- |
| **All** (default) | LLM input, LLM output, tool input, tool output |
| **Input**         | LLM input + tool input                         |
| **Output**        | LLM output + tool output                       |

Search runs in addition to any structured filters — both must match for a span to appear in results.

#### Sorting in the UI

The grid is sorted by **Timestamp** (most recent first) by default. Click the **Timestamp** or **Duration** column header to change the sort. Other columns are not sortable in the UI in this release.

#### Opening the trace drawer

To inspect the full trace context for a span, click the **View Trace** (eye) icon in the rightmost **Actions** column. This opens a side drawer that loads every span in the row's session and renders them as a tree.

* The drawer is **session-scoped**, not trace-scoped — if a session contains multiple traces, all of them are visible in the drawer.
* The View Trace icon is **disabled** for spans without a `session_id`, with the tooltip *"No trace found"*.

***

### Related Resources

* [Custom Metrics for Agentic Applications](/observability/agentic/custom-metrics.md) — define custom metrics over the same span data using FQL
* [Span and Resource Attributes](https://github.com/fiddler-labs/fiddler/blob/release/26.10/docs/integrations/agentic-ai/attributes.md) — full attribute catalog and naming conventions
* [Agentic Observability](/observability/agentic.md) — overview of dashboards, metrics, and integrations
* [OpenTelemetry Trace Export](https://github.com/fiddler-labs/fiddler/blob/release/26.10/docs/integrations/agentic-ai/otel-trace-export.md) — export pre-existing OpenTelemetry traces to Fiddler from your own storage or pipeline

***

### Limitations & Roadmap (Public Preview)

The following are not available in this release and are tracked for future work:

* **Session-attribute filters.** You can filter by `session_id`, but filters over session-level attributes are not yet supported.
* **Multi-pattern structural filters.** Constructs such as "trace contains tool X *then* LLM Y" or "trace where root has positive feedback" — sometimes written with `->` (temporal) or `=>` (parent / child) operators in other tools — are not yet supported.
* **Saved filter sets.** Filters live for the current session; they cannot be named, saved, or shared yet.
* **CSV / notebook export.** Bulk export of filtered results is not yet available.

We're prioritizing these based on customer feedback during public preview — please reach out to your Customer Success Manager or file a ticket if any of the above are blocking your workflow.


---

# Agent Instructions: 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:

```
GET https://docs.fiddler.ai/observability/agentic/trace-explorer.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.