# Trace Details

The **Trace Details** interface in SigNoz offers a powerful and intuitive interface to visualize and analyze the journey of a request through your system. By displaying detailed trace information, it enables you to quickly diagnose performance issues, pinpoint errors, and understand the intricate flow of operations in your systems. It is engineered to handle massive trace data supporting more than a **million spans per trace** making it an ideal solution for high-volume environments.

The Trace Details Page enables you to:

- **Visualize the Entire Trace:** Render large traces seamlessly using synchronized flame graphs and waterfall charts.
- **Drill Down Into Details:** Inspect individual spans to view metadata, span percentile, context, attributes and events associated with each span.
- **Efficient Navigation and Search:** Use the dynamic search bar, quick filters, and highlight errors to quickly jump to specific spans or error events.
- **Responsive and Scalable:** Handle traces from your architectures (monolithic or microservices) without performance lag, ensuring smooth and real-time analysis.

## Key Concepts

- **Trace:** A trace represents the complete path a request takes through your system, helping you understand its flow across various components and services.
- **Span:** Spans are the building blocks of a trace, representing individual units of work performed by an application or service during the request's lifecycle. Key components of a span include:
  - **Span Context:** Metadata that links spans across services, enabling distributed tracing and hierarchical structuring.
  - **Span Attributes:** Key-value pairs that store additional metadata about the operation performed by the span.
  - **Span Links:** References that establish causal relationships between spans, useful for correlating asynchronous operations or background tasks with the main trace.
  - **Span Events:** Structured log messages that record important events at specific timestamps during the span's execution.

## Opening a Trace

Select a trace from the [Trace Explorer](/content/docs/userguide/traces/index.html) to open the Trace Details page. You will see two synchronized views:

- **Flame Graph** — displays a hierarchical representation of the trace, showing the nested relationships between spans. The header shows the total span count and error count. It can render **100,000+ spans** at once.
- **Waterfall Chart** — provides a detailed timeline view, illustrating the sequence and duration of each span. It supports **10,000+ spans** with virtual scrolling for smooth navigation.

Both views are collapsible — click the section header to expand or collapse them and maximize screen space.

## Inspecting a Span

Click on a specific span in either the flame graph or waterfall view to open the **Span Details** panel. The panel is a floating, resizable window that can be docked to the right side or bottom of the screen, allowing you to arrange your workspace.

The panel header shows:

- **Span name** and **service name**
- **Percentile ranking** (e.g., p52, p100) and duration
- **Percentage of total execution time**
- **Timestamp** and **linked spans count**
- **Service**, **Status Code**, **Trace ID**, and **Span Kind**

The details are organized into tabs:

- **Overview** — span attributes in a structured view
- **Events** — timestamped log messages and span events recorded during the span
- **Logs** — correlated log lines from the span's service and time window
- **Metrics** — infrastructure metrics (CPU, memory) for the host or pod

### Attributes

The Overview tab displays all resource and span attributes. You can toggle between **Pretty** and raw views:

- **Pretty view** — displays attributes in their original, nested JSON structure as ingested, making it easier to understand complex attribute hierarchies.

Hover over any attribute value to see quick action icons:

- **Pin Attribute** — pin the attribute to the top of the list for easy reference
- **Filter for Value** — add the attribute as an `IN` filter to the current query
- **Filter out Value** — add the attribute as a `NOT IN` filter to exclude matching spans
- **Group By Attribute** — add the attribute to the Group By clause
- **Copy Field Name** — copy the attribute key to your clipboard
- **Copy Field Value** — copy the attribute value to your clipboard

### Span Percentile

When you view a span's details, you can see its percentile compared to other spans from the same service over the past hour (for example, p50, p90, p95, p99). The percentile information may take a few seconds to appear after opening the span details. This helps you quickly identify performance outliers and understand where the span falls within the typical latency distribution.

Click on the percentile to view more details, including the exact p50, p90, and p99 values for the matching spans.

You can further refine this analysis by adding more resource attributes to narrow down the set of similar spans, or by increasing the time range to observe percentile behavior over a longer period.

### Synchronized Navigation

The flame graph and waterfall views remain perfectly synchronized. Clicking a span in one view automatically highlights it in the other and opens the Span Details panel, ensuring you always see where a span fits into the overall trace timeline.

## Analytics

Click the **Analytics** button in the top bar to open the Analytics panel. It provides a quick breakdown of your trace by service, with two views:

- **% exec time** — shows each service's share of the total trace execution time
- **Spans** — shows span count distribution across services

## Options Menu

Click the **three-dot menu** (⋯) in the top bar to access additional trace options:

- **Hide trace details** — collapses the sub-header row that displays the service name, operation, duration, timestamp, and status code
- **Preview fields** — opens a panel where you can select span attributes to display inline in the waterfall rows, so you can see key values without opening the Span Details panel
- **Colour by** — choose how spans are colored in the flame graph and waterfall (e.g., by `service.name` or `host.name`)

### Preview Fields

The Preview fields panel lets you search for and select up to 10 span attributes to display as inline previews in the waterfall. This is useful for surfacing key information (like HTTP status codes or database statements) directly in the trace timeline without opening individual spans.

### Colour By

The Colour by submenu lets you customize how spans are colored in the flame graph and waterfall views. The following attributes are available:
- `service.name`
- `service.namespace`
- `host.name`
- `k8s.node.name`
- `k8s.container.name`

These options appear in the list when the corresponding attributes are ingested in your trace data. If an attribute is not present in your spans, it won't show up as an option.

## Waterfall Hover Tooltip

Hover over any span row in the waterfall to see a tooltip with key details:
- **Span name** — the operation name
- **Status** — whether the span completed successfully or with an error
- **Start** — the span's start time relative to the trace start
- **Duration** — how long the span took

You can add more fields to the tooltip by selecting attributes through the **Options menu (⋯) → Preview fields**. Any attribute you add there (up to 10) will also appear in the hover tooltip alongside the default fields.

## Filtering and Analysis

The Trace Details page provides multiple ways to filter and analyze spans within a trace.

### Highlight Errors

Toggle **Highlight Errors** in the top-right corner to instantly focus on error spans. When enabled:
- A `has_error = true` filter is applied automatically
- Non-error spans are **dimmed**, making red error spans stand out
- A **counter** (e.g., 1 / 3) appears, letting you navigate between error spans using the up/down arrows

### Quick Filters

Quick filter buttons at the top of the page provide one-click filtering by span kind:
- **All** — show all spans
- **Database** — filter to database operations
- **Functions** — filter to function calls
- **HTTP** — filter to HTTP spans
- **Jobs** — filter to job/task spans
- **LLM** — filter to LLM-related spans

These filters can be combined with the Highlight Errors toggle for targeted analysis.

### Query Builder

The integrated query builder allows you to write custom filter queries directly in the filter bar. For example:
- `http.status_code >= 500 AND service.name = 'frontend'` — find server errors in a specific service
- `http.method exists` — filter to HTTP spans only

## Adjusting the Interface

The Span Details panel opens by default as a **docked panel on the right**. You can switch between three layout modes using the dock buttons in the panel header:
- **Dock to the right** (default) — panel appears on the right side, ideal for viewing attributes alongside the trace
- **Dock to the bottom** — panel appears at the bottom, maximizing the horizontal trace view
- **Floating panel** — panel detaches into a free-floating window that can be **resized in all directions** and **moved anywhere** on screen, giving you full control over your workspace layout

You can also close the panel entirely and reopen it by clicking any span.

## Related Signals

The Span Details panel includes **Logs** and **Metrics** tabs that let you jump directly to correlated signals for the selected span — without leaving the trace view.

### Logs

Click the **Logs** tab to see log lines correlated to the span's time window and service. The panel shows log entries with timestamps and message bodies.

### Metrics

Click the **Metrics** tab to see infrastructure metrics (CPU usage, memory usage) for the host or pod that served the selected span. Use the **Node** and **Pod** tabs to switch between host-level and pod-level views.

## Legacy View

If you prefer the previous trace details interface, click the **Legacy View** button in the top-right corner to switch back. SigNoz remembers your preference for future visits.