Last updated: March 23, 2026
Write PromQL Queries
The PromQL tab in the Query Builder gives you a full-featured PromQL editor for cases that go beyond what the visual tabs support.
Use it when you need arithmetic across metrics, multi-label grouping, custom functions, or any other operation that requires direct query authorship.
Type a PromQL expression directly in the editor. The editor provides syntax highlighting. The preview chart above updates as you type.
Common starting points:
- Start from any PromQL Preview shown in one of the other tabs in the Query Builder — it is a valid, copy-paste-ready expression.
- Use
increase({otel_metric_name = "dash0.spans.duration"}[$__interval])to query span duration data. - Use
sum(increase({otel_metric_name = "dash0.logs"}[$__interval])) > 0to count logs over time.
The $__interval placeholder is automatically replaced by Dash0 based on the selected time range, keeping step sizes appropriate.
Format and Explain
Two actions are available below the editor:
- Format — reformats the query to standard PromQL indentation and style without changing its semantics.
- Explain — parses the query and shows a human-readable breakdown of what each part does, which is useful when learning PromQL or debugging an unfamiliar expression.
Extend a Visual Query
A common workflow is to start with a visual tab to get the basic shape of a query, then switch to PromQL to add complexity:
- Build the base query in the Services, Tracing, Logging, Metrics, or Web Events tab.
- Click the PromQL tab — the generated query appears in the editor.
- Extend it — for example, add a
by (service_name, http_method)clause to group by two dimensions at once, or divide one metric by another to compute a ratio.
Once you switch to the PromQL tab and edit the query manually, switching back to a visual tab will not reconstruct the visual controls from your PromQL. Treat the switch as a one-way escalation for the current session.
Use PromQL Queries in the Dash0 API
Any expression you write or generate in the Query Builder can be used in the Dash0 API directly.
Copy the expression from the PromQL editor or from the PromQL Preview in any visual tab and use it in your API calls to query time series data programmatically.
Promote the Query
Once you have the view you want, use the buttons at the top of the Query Builder, above the preview chart.
- Click Add to dashboard to add the current query as a panel to a new or existing dashboard.
- Click Create check rule to open the check rule editor with this query pre-filled as the rule expression.
