> ## Documentation Index
> Fetch the complete documentation index at: https://metoro.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PromQL

> Query Metoro metrics with PromQL

<Warning>
  PromQL support is currently alpha. It is intended to help you reuse existing PromQL and Grafana queries, but there may be minor correctness differences from Prometheus and performance is generally not as strong as native [MetoroQL](/docs/metrics/metoroql).
</Warning>

Metoro supports PromQL as a query mode for metric dashboard widgets. This is useful when you already have PromQL queries from Prometheus, Grafana, or another Prometheus-compatible workflow and want to bring them into Metoro with minimal changes.

For new dashboards and long-term Metoro workflows, use [MetoroQL](/docs/metrics/metoroql) by default. MetoroQL is the native query language, is generally faster, and can query metrics, logs, traces, and Kubernetes resources with one syntax.

## When to use PromQL

Use PromQL when:

* You are migrating existing Prometheus or Grafana dashboards.
* You want to reuse familiar PromQL metric queries.
* You need a quick compatibility path for Prometheus-style metric expressions.

PromQL mode is focused on metric queries. It is not a replacement for MetoroQL's cross-domain querying over logs, traces, and Kubernetes resources.

## When to use MetoroQL

Use MetoroQL when:

* You are building a new dashboard in Metoro.
* Query correctness and performance matter more than PromQL compatibility.
* You want to query logs, traces, Kubernetes resources, or combine observability domains.
* You want the query behavior Metoro optimizes most heavily.

MetoroQL is also the better choice when a PromQL query shows unexpected results or takes longer than expected to run.

## Use PromQL in dashboards

To use PromQL in a dashboard widget:

1. Open a dashboard and click **Edit**.
2. Add or edit a metric widget.
3. Open the query mode selector.
4. Choose **PromQL mode**.
5. Enter your PromQL query and save the widget.

PromQL can be used in dashboard metric widgets that expose the query mode selector, such as charts, tables, stats, gauges, bar gauges, and pie charts.

## Examples

Query a metric and group by service:

```PromQL theme={null}
sum(container_resources_cpu_usage_seconds_total) by (service_name)
```

Filter a metric by namespace:

```PromQL theme={null}
avg(container_resources_memory_rss_bytes{namespace="default"}) by (pod)
```

Use a rate-style query for a Prometheus counter:

```PromQL theme={null}
sum(rate(http_requests_total{service="api"}[5m])) by (status_code)
```

Calculate a histogram percentile:

```PromQL theme={null}
histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))
```

## Limitations

PromQL support is alpha and has some important limitations:

* Results may have minor correctness differences from Prometheus, especially for edge-case PromQL semantics.
* PromQL queries are generally slower than equivalent native MetoroQL queries.
* A widget expression runs in one query mode at a time. PromQL queries cannot be mixed with standard metric queries, formulas, or MetoroQL queries in the same expression.
* Public dashboard metric queries do not currently support PromQL-backed widgets.
* PromQL mode is for metric queries only. Use MetoroQL for logs, traces, and Kubernetes resources.

<Note>
  If a PromQL query is unexpectedly slow or does not match Prometheus exactly, try rewriting it in [MetoroQL](/docs/metrics/metoroql). MetoroQL is the native path and is the preferred option for production dashboards.
</Note>