Since its initial development in 2012 alongside Prometheus, PromQL has been a cornerstone of time-series monitoring for over a decade. While Kibana already comprehensively supports time-series analysis via the ES|QL TS command, we are thrilled to introduce native PromQL support for common metrics analytics use cases. For teams already fluent in PromQL, this support means a near-zero learning curve and significantly easier onboarding directly into the Elastic ecosystem.
Running PromQL queries in Kibana
In the ES|QL editor in Kibana, enter the PROMQL command, and type your PromQL in that block.
PROMQL marks that segment so Elasticsearch parses it as PromQL inside the wider ES|QL request Kibana sends.
What you can query
Here are a few patterns to get started.
Raw metric
PROMQL container.cpu.usage
Average across all containers
PROMQL avg(container.cpu.usage)
rate() on a counter
PROMQL rate(docker.network.inbound.bytes)
Aggregated rate
PROMQL sum(rate(docker.network.inbound.bytes))
Group by a label
PROMQL sum by (agent.id) (rate(docker.network.inbound.bytes))
You may notice that none of these examples include start, end, step, or a lookback window on every rate().
Those parameters are optional: the time picker and Kibana defaults handle most of it for you.
Optionally, you can include the data stream name using the index= parameter.
For example: PROMQL index=metrics-docker.cpu-default container.cpu.usage.
Adding the parameter helps narrow down the scope of what data the query scans.
The current release of PromQL tech preview has over 80% query coverage benchmarked against top Grafana dashboards. Advanced modifiers and specific functions are in consideration for future releases.
Find your streams and metric names
If you have existing PromQL queries, you can use them directly in the PROMQL command without changes.
If you are writing a query from scratch and need to find the exact field names, run TS metrics-* in Discover to see every metrics data stream.
Each metric appears as a small chart so you can tell at a glance what is active.
Hover over a metric and click the "View details" action to see the field name and the data stream it belongs to.
For a deeper walkthrough, see Explore metrics data with Discover in Kibana.
Time picker and query time handling
The time picker in Kibana sets the time window for the query.
Dashboard panels and Alerting rules work the same way using their own time range, so you do not need to write start= or end= in the query itself.
Step is the gap between two consecutive data points on the chart.
A smaller step means more data points across the same span.
If you do not set step= or buckets=, the default is buckets=100.
You can set step= to a fixed width such as 1m, or set buckets= to a different target maximum number of data points.
Discover and Dashboards
In Discover, switch to ES|QL mode and run your PROMQL query so you can see how the metric behaves over the range you pick, as a time-series chart.
When you want to save that visualization, choose "Save visualization to dashboard" and add it to a new or existing dashboard.
Or go to Dashboards directly: add a panel, choose ES|QL, and write your PROMQL query.
Alerting
You can create alert rules using PromQL. Go to Alerts, open Manage rules, and create a rule. Search for Elasticsearch query and select it. Choose ES|QL as the query type.
Write your PROMQL query, but assign the metric to a variable so you can use it in a WHERE clause for the alert condition:
PROMQL metric_value=(sum by (agent.id) (rate(docker.network.inbound.bytes)))
| WHERE metric_value >= 500
Select @timestamp for the time field and continue defining the rest of the rule configuration.
Try it
- Open an Observability project on Elastic Cloud Serverless, or use Elastic Stack 9.4.
- Write your query: in the ES|QL editor in Kibana, run your PromQL via
PROMQL. You can also go to Dashboards, add a panel, choose ES|QL, and write the query there. - If you are writing from scratch and need to find metric names, run
TS metrics-*in Discover (see "Find your streams and metric names" above). - Check the results and adapt the query if needed.
PromQL support in Elasticsearch and Kibana will continue to evolve. Follow the Observability Labs feed for follow-up posts as coverage and ergonomics improve.