Widgets
Available widget types — stat cards, time-series charts, distributions, pivot tables, and custom SQL — and how to configure them.
Widgets
Widgets are the building blocks of dashboards. Each widget defines a data source (view), the metrics and dimensions to query, filters, and a chart type to render the result.
Widget Types (Chart Types)
Stat Card (Big Number)
Displays a single aggregated value — for example, total traces in the last 7 days or average p95 latency. Best for at-a-glance KPIs.
- No dimension breakdown supported
- Supports all aggregation functions (
sum,avg,count,min,max, percentiles)
Time-Series Charts
Plot a metric over time. Two variants:
| Variant | When to use |
|---|---|
| Line Chart | Trends and rate changes (latency, score averages) |
| Bar Chart (time-series) | Volume metrics (trace count, token usage) |
Time-series widgets support a granularity setting: auto, hour, day, week, or month. auto picks the best granularity based on the selected date range.
Optional dimension breakdown groups the time-series by a dimension field (e.g. model name, environment). Each group is rendered as a separate series.
Bar Charts
| Variant | When to use |
|---|---|
| Horizontal Bar | Ranking/comparing categories (e.g. top models by cost) |
| Vertical Bar | Comparing values across a small number of categories |
Both support dimension breakdown.
Pie Chart
Shows the proportional share of each dimension value for a metric. Best for 5 or fewer categories.
Score Distribution
Renders a distribution (histogram) of numeric score values. Useful for understanding how evaluation scores spread across traces. Does not support dimension breakdown.
Pivot Table
Cross-tabulates two dimensions against a metric. Dimensions become row and column headers; cells show the aggregated metric value. No chart breakdown is available; the table itself is the visualization.
Scatter Plot
Plots two metrics against each other (e.g. latency vs. cost per trace) to reveal correlations.
Custom SQL Widget
Write a raw ClickHouse SQL query and render the result as any chart type. Use ?from and ?to as query parameters for time range injection:
SELECT
toStartOfDay(timestamp) AS time_dimension,
model AS dimension,
sum(total_tokens) AS metric
FROM observations
WHERE project_id = currentSetting('projectId')
AND timestamp BETWEEN ?from AND ?to
GROUP BY time_dimension, dimension
ORDER BY time_dimensionSQL widgets are capped at 1,000 result rows server-side. Use LIMIT in your query to control output size.
Adding a Widget to a Dashboard
Open the Add Widget dialog
On any custom dashboard, click the + (Plus) icon in the top-right corner.
Browse or search for a widget
The dialog lists all widgets available in the project. Use the search bar to filter by name. Widgets already on the current dashboard are highlighted.
Select the widget
Click the widget to add it. It is placed at the top of the dashboard grid and the page scrolls to it with a brief highlight animation.
Creating a New Widget
Widgets are created and managed independently from dashboards. To create a new widget:
Open the widget builder
In the Add Widget dialog, click Create New Widget, or navigate to a dashboard and select New Widget from the actions menu.
Choose a data view
Select the data source the widget queries:
| View | What it contains |
|---|---|
| Traces | One row per trace (request/operation) |
| Observations | One row per span, generation, or event within a trace |
| Sessions | One row per session (multi-turn conversation) |
| Scores (numeric) | Numeric evaluation score values |
| Scores (categorical) | Categorical evaluation score values |
Select a chart type
Pick one of the chart types listed above. The chart type determines which configuration options appear next.
Configure metrics and dimensions
- Metrics — choose one or more measure + aggregation pairs (e.g.
totalCostwithsum,latencywithp95) - Dimensions — choose fields to group by (e.g.
name,environment,providedModelName) - Filters — add conditions to restrict which rows are included (e.g.
environment equals production)
Set the date range
Choose a date preset (e.g. Last 7 days) or set a custom range. This controls the default time window shown when the widget loads.
Save the widget
Click Save. The widget is now available to add to any dashboard in the project.
Editing and Removing Widgets
- To edit a widget's configuration, open the widget's ⋮ menu on a dashboard and select Edit Widget.
- To remove a widget from a dashboard, select Remove from Dashboard. This does not delete the widget — it remains available for other dashboards.
- To delete a widget entirely, open the widget management view and select Delete Widget. This removes it from all dashboards.
Widgets owned by TESTOPS (system widgets) cannot be edited. Use the Clone option to create an editable copy.