PromQL compatibility

Uptrace aims to be compatible with the Prometheus query language while extending it in a meaningful way. Most Prometheus queries can be used in Uptrace with minimal modifications, for example, the following Prometheus queries are also valid in Uptrace:

$metric_name{foo="xxx",bar~"yyy"}
increase($metric_name) and delta($metric_name)
rate($metric_name[5m]) and irate($metric_name[5m])
avg_over_time($go_goroutines[5m])
avg by (foo)(sum by(foo, bar)($metric_name))
$metric_name offset 1w
Math between series with automatic many-to-one/one-to-many vector matching, for example, sum($mem by (type)) / sum($mem) as mem.

The metrics query language reference lists every function Uptrace supports, and marks the ones Prometheus does not have.

But there are also some differences between the systems that don't allow you to just copy and paste queries from Prometheus. To ease the migration, you can use Uptrace as a Prometheus data source in Grafana, which is 100% compatible with the original Prometheus and allows you to use existing Grafana dashboards.

Aliases

Uptrace requires a short alias for every metric, which PromQL does not. This is the one change every copied query needs: declare the metric once, then write the alias in the query.

yaml

metrics:
  - node_memory_MemFree_bytes as $mem_free
  - node_memory_Cached_bytes as $cached

query:
  - $mem_free + $cached

Expression aliases, and referencing them across the | separator, work the same as in any Uptrace query — see aliases.

Grouping

Just like Prometheus, Uptrace allows to customize grouping, for example, the following queries return the same result in Uptrace and Prometheus:

shell

sum by (cpu, mode)(node_cpu_seconds_total)
sum(node_cpu_seconds_total) by (cpu, mode)

avg by (cpu)(sum by (cpu, mode)(node_cpu_seconds_total))
avg(sum(node_cpu_seconds_total) by (cpu, mode)) by (cpu)

Filtering, joining, attribute manipulation, and the conditional operators behave the same as in any Uptrace query — see Querying metrics.

Rate interval

Prometheus and Grafana make you size the lookbehind window yourself. Uptrace picks one for rate and irate, so you can leave it out:

shell

# Grafana and Prometheus
irate(node_cpu_seconds_total[$__rate_interval])

# Uptrace
irate(node_cpu_seconds_total)

The window Uptrace picks is max(5 × interval, 5m), where the interval is the current grouping step. Set your own in square brackets when you need it — irate($metric[5i]), where i is one interval. Every other rollup function reads only the current interval unless you give it a window.

Range vs instant vectors

Because Uptrace does not distinguish between range and instant vectors, you should omit the lookbehind window and let Uptrace pick a default for you:

shell

# Omit the window by default.
irate(node_cpu_seconds_total)

# Only specify it when needed.
max_over_time(process_resident_memory_bytes[1d])