PromQL

PromQL
Name	PromQL
Paradigm	Functional, declarative
Designer	Prometheus authors
First appeared	2012
Typing	Dynamic
Influenced by	None

PromQL PromQL is a domain-specific query language developed for time-series monitoring and alerting, originating from the Prometheus (software). It enables expressive selection, aggregation, and arithmetic over metrics collected from targets such as Kubernetes, Docker, Apache HTTP Server, NGINX, and MySQL. PromQL is widely used in observability stacks alongside systems like Grafana, Thanos, Cortex (software), Alertmanager, and VictoriaMetrics.

Overview

PromQL was created within the Prometheus (software) project, which began at SoundCloud and later became part of the Cloud Native Computing Foundation. It addresses needs encountered in large-scale deployments including those at CoreOS, Red Hat, Google, Amazon Web Services, Microsoft Azure, and IBM cloud environments. Operators and SREs from organizations such as Netflix, Spotify, Airbnb, Slack Technologies, and Shopify adopted PromQL for metrics-driven troubleshooting, capacity planning, incident response, and continuous deployment workflows with tools like Jenkins and GitLab.

Syntax and Semantics

PromQL expressions combine metric selectors, label matchers, range selectors, aggregation operators, binary operators, and functions. The language syntax allows selecting series by metric name and labels, similar to how Berkley Packet Filter uses syntax to select packets or how SQL selects rows, but tailored to the semantics of metrics produced by exporters such as node_exporter, blackbox_exporter, mysql_exporter, and cadvisor. Prometheus servers evaluate PromQL queries at specific instants or over ranges, comparable to how InfluxDB and OpenTSDB evaluate time-series queries in their ecosystems. The design balances expressiveness and performance, influenced by engineering practices at Google SRE and principles from projects like Graphite.

Data Model and Time Series

Prometheus’s data model represents each time series as a stream of timestamped samples identified by a metric name and a set of labels. This approach is similar to labeling concepts used by Kubernetes metadata, Consul service tags, and etcd keys. Instrumentation libraries for languages and frameworks such as Go (programming language), Java, Python (programming language), Ruby, and Node.js produce metrics consumable by Prometheus via the exposition format, comparable to metrics formats used by StatsD and OpenTelemetry. Time-series cardinality issues encountered in environments like Facebook and Twitter have driven best practices around label usage and exporter design.

Operators and Functions

PromQL provides arithmetic operators (+, -, *, /), comparison operators (==, !=, >, <), and set operators (and, or, unless) for combining selectors and results. A rich set of functions supports rate computation, statistical aggregation, and time-based transformations: examples include rate(), increase(), delta(), irate(), histogram_quantile(), and topk(). These capabilities echo functionality found in analytic systems like R, MATLAB, and Pandas (software), while being optimized for streaming and near-real-time evaluation as practiced by teams at Spotify Engineering, Uber, and Airbnb Engineering.

Aggregation and Grouping

Aggregation in PromQL uses operators such as sum, avg, min, max, count, and stddev, often with by and without grouping modifiers to control label dimensions. Techniques for roll-up and down-sampling integrate with long-term storage backends like Thanos, Cortex (software), InfluxDB, and VictoriaMetrics, and are employed by large-scale deployments at companies including Bloomberg, Salesforce, and Pinterest. Grouping strategies are analogous to tagging and aggregation approaches in Elasticsearch and Splunk logs, facilitating multi-dimensional analysis across services such as PostgreSQL, MongoDB, Redis, and HAProxy.

Use Cases and Integrations

PromQL is used for alerting rule definitions in Alertmanager workflows, dashboards in Grafana, and ad hoc queries during incident response at organizations like GitHub, GitLab, Stripe, and DigitalOcean. It integrates with orchestration and service meshes such as Istio, Linkerd, Envoy (software), and Traefik, and with CI/CD pipelines in Travis CI and CircleCI. Data exporters and receivers include Prometheus exporters, OpenTelemetry Collector, and proprietary agents from Datadog, New Relic, and Dynatrace, enabling cross-system observability with business platforms like Salesforce and SAP.

Performance and Best Practices

Performance considerations in PromQL center on cardinality, query complexity, retention, and storage engine choices. Techniques adopted by large cloud providers such as Google Cloud Platform, Amazon Web Services, Microsoft Azure, and projects like Thanos include remote read/write, downsampling, compaction, and sharding. Best practices encourage limiting label cardinality, using recording rules for expensive expressions, pre-aggregating metrics in exporters, and leveraging tools like Prometheus Operator and Kube-prometheus-stack for scalable deployments in Kubernetes clusters. Case studies from Red Hat OpenShift, Canonical deployments, and engineering teams at Spotify show measurable gains when combining architectural patterns and query optimizations.

Category:Query languages