PromQL Query Builder & Explainer

A PromQL query builder is a tool for creating expressions in Prometheus Query Language, the query language used to select and calculate values from Prometheus time-series metrics. It can help developers construct metric selectors, label matchers, range functions and aggregations without assembling every expression from memory.

AabiTech combines a visual query builder with a PromQL editor, reusable examples, a query explainer and selected rule-based diagnostics. It is intended as a practical companion to Prometheus documentation and your monitoring environment, not a replacement for testing queries against real data.

1. Enter a metric name that is available in your Prometheus server.
2. Add label matchers such as job="api" or status=~"5.." to select the relevant series.
3. Choose a range function such as rate() when working with a counter over a time window.
4. Select an aggregation such as sum and specify grouping labels when needed.
5. Review the generated PromQL, read its explanation and check parser diagnostics.
6. Run the query in your own Prometheus or Grafana environment and verify the returned series.

Metric names, labels and suitable range windows depend on your instrumentation, scrape interval and monitoring goal.

The explainer identifies recognized metric selectors, functions, aggregation patterns and range windows, then describes their usual purpose in plain language. This is useful when reviewing a query written by a teammate, learning PromQL syntax or understanding a monitoring dashboard.

Explanations are static and pattern-based. Complex nested expressions, experimental functions, newer language features and environment-specific semantics may not be described completely. A readable explanation does not prove that a query is valid for your metric data or produces the intended result.

The editor integrates a PromQL language extension for syntax highlighting, autocomplete and parser diagnostics. Additional static checks flag selected patterns, including potentially incorrect rate/aggregation order, classic histogram queries that may not preserve the le label, broad regular-expression matchers and example metric names.

Static checks are advisory. Some flagged patterns may be intentional, and a query with no warnings can still be incorrect, expensive or incompatible with the labels in your environment. For definitive validation, use a Prometheus server with the same version and relevant data as production.

rate() estimates the per-second average rate of increase of a counter over a range and is commonly used for request rates. increase() estimates the total increase over a range. irate() calculates an instant rate from the last two samples and can be more volatile.

For counters, apply rate() or increase() to each series before aggregating so counter resets can be handled per series. Choose a range that provides enough samples for your scrape interval and desired responsiveness.

Aggregators such as sum, avg, min, max and count combine values across input series. The by(...) modifier retains the specified label dimensions, while without(...) aggregates while excluding the named labels.

Choose grouping labels based on the question you need to answer. Grouping by high-cardinality labels can produce many output series, while removing important dimensions may hide differences between services, instances or endpoints.

For classic Prometheus histograms, histogram_quantile() commonly operates on bucket rates while preserving the le bucket label. A typical p95 pattern is histogram_quantile(0.95, sum by (le, job) (rate(http_request_duration_seconds_bucket[5m]))).

Replace the example metric and grouping labels with the ones your application exposes. Native histograms have different query considerations, so do not assume that every histogram metric uses classic bucket series.

The template library includes common patterns for HTTP request rates, 5xx error ratios, histogram latency percentiles, CPU and memory utilization, filesystem usage, unavailable scrape targets, Kubernetes container restarts, firing alerts and top-valued series.

Templates are starting points, not universal drop-in queries. For example, an HTTP error query assumes an appropriate status label, while Node Exporter and Kubernetes examples assume their respective exporters and metric names are present. Adapt selectors and exclusions to your own environment.

The alert helper generates a draft YAML rule for a common HTTP 5xx error-ratio scenario. You can set the alert name, metric, threshold, evaluation window, grouping labels and description, then copy the draft for review.

The output is a template and is not automatically validated against your metric schema, Prometheus version or alerting policy. Confirm that the status label and counter semantics are correct, test the expression, validate the YAML and review the alert's behavior before deploying it.

PromQL binary operations between instant vectors match series using their labels unless modifiers such as on(...), ignoring(...), group_left or group_right change the matching behavior. Unexpected label sets can lead to empty results or many-to-many matching errors.

A static browser tool cannot inspect your actual label sets. When a query returns no data or a vector-matching error, compare the labels on both sides of the expression in Prometheus, then adjust the matching modifiers only when the intended relationship is clear.

The builder, static explanations and local diagnostics operate in the browser. The tool does not need a Prometheus connection to construct a query and does not execute the expression against a monitoring server.

The PromQL editor's core language features are configured for offline use; remote metric autocomplete is not enabled. As with any website, normal page requests and hosting infrastructure may process standard connection data. Do not paste credentials, tokens or confidential query information into any online tool unless you are comfortable with the site's applicable privacy terms.

• No data: verify the metric name, label values, time range and scrape status.
• Unexpected aggregation: review by and without labels and check whether important dimensions were removed.
• Counter rate looks wrong: apply rate() before aggregation and use a suitable range window.
• Histogram percentile is incorrect: check the metric type and preserve le for classic histograms.
• Many-to-many matching error: inspect the labels on both sides of a binary vector operation.
• Slow query: narrow selectors where possible and review range duration, series cardinality and aggregation choices.

These checks guide investigation; the actual cause must be confirmed against the target Prometheus environment.