From 539b1fb7aa1fc57539162b4774e37dcfac829303 Mon Sep 17 00:00:00 2001 From: Julien Danjou Date: Mon, 27 Jul 2026 16:15:03 +0200 Subject: [PATCH] docs(merge-queue): describe the Statistics page as it ships "Monitoring your Merge Queue" listed six freeform metrics that no longer line up with the dashboard. The Statistics page groups its widgets into Queue Health, Throughput and Performance under a row of headline figures, and gained two things this quarter the page never mentioned: the Time Breakdown widget's Avg/P95/Max selector, and the Batches Saved chart. Rewrite the section to follow the page: every widget by its real name, what it tells you, and the reference-line semantics for Max Queue Size (max batch size times max_parallel_checks) and Average Batch Size (the largest configured batch_size). The Time Breakdown entry explains the selector and why the center total only appears for the average: p95 and max of the components are not additive. Also correct the retention claim while it moves. The "Past 3 months" preset spans roughly 91 to 92 days against 90 days of queue-event retention, so its oldest day or two come back empty; the page promised that every preset returned complete data. MRGFY-8213 Co-Authored-By: Claude Opus 5 (1M context) Change-Id: Ifebfad2ca0cf287237bc55cc421b3c0cf4c0defe --- src/content/docs/merge-queue/monitoring.mdx | 101 ++++++++++++++------ 1 file changed, 71 insertions(+), 30 deletions(-) diff --git a/src/content/docs/merge-queue/monitoring.mdx b/src/content/docs/merge-queue/monitoring.mdx index 47e37c7a9e..fee333e4c0 100644 --- a/src/content/docs/merge-queue/monitoring.mdx +++ b/src/content/docs/merge-queue/monitoring.mdx @@ -9,46 +9,87 @@ import dashboardStatsScreenshot from "../../images/merge-queue/monitoring/dashbo Monitoring your merge queue's key metrics helps you identify bottlenecks, optimize throughput, and maintain an efficient development cycle. -## Key Metrics to Monitor +## The Statistics Page -### PRs Merged Per Day -Track the number of pull requests merged each day. A consistent trend indicates -a stable development environment. Sudden drops or spikes can indicate issues -that need attention. +Open **Merge Queue → Statistics** in your +[dashboard](https://dashboard.mergify.com) to see how your queue is behaving: -### CI Runtime -Monitor how long your Continuous Integration tests take to run. A sudden -increase in runtime can slow down your entire merge queue and delay other PRs. +Statistics page on Mergify's dashboard -### Queue Checks Outcome -Track the success rate of PRs in the queue. High success rates indicate a -healthy development and review process. Frequent failures may signal a need for -process refinement or CI improvements. +Use the date picker to select the time range you want to review. Presets go up to +"Past 3 months". Queue data is retained for 90 days, so the oldest day or two of +that longest preset can come back empty. A repository selector and filters narrow +every widget on the page at once. -### Queue Size -Monitor the number of PRs waiting in the queue. If the queue grows -significantly or continuously, it indicates a bottleneck or inefficiency in -your process or CI. +A row of headline figures sits at the top: pull requests entered and merged, the +merged rate, time spent waiting for CI, max queue size, throughput, queue time, +CI runtime, and CI failure rate. Below it, the widgets are grouped into three +sections. -### Running Checks -Monitor the number of checks currently running. If you're often at full -capacity, consider increasing the number of parallel checks to improve -throughput. +### Queue Health -### Queue Waiting Time -Track how long PRs spend idle in the queue. Extended waiting times increase -overall latency and can delay the delivery of features or fixes. +Exit reasons, interruptions, and failure trends. -## Viewing Your Metrics +- **PR Exit Reasons**: how pull requests leave the queue. The distribution view + counts each pull request once by its final exit reason; the over-time view + shows how those reasons trend. -View these metrics on the merge queue page of your -[dashboard](https://dashboard.mergify.com): +- **Batch Outcomes**: the outcome of every CI run the queue triggered, including + batch results, [bisection](/merge-queue/batches#handling-batch-failure-or-timeout) + attempts, and queue resets. One pull request can produce several runs. -Statistics page on mergify's dashboard +- **Checks Retries**: how often checks are retried, and how often a retry ends in + a merge. A low recovery rate points at genuinely broken tests rather than + flaky ones. -Use the date picker to select the time range you want to review. Presets go up to -"Past 3 months", and data is retained for 90 days so every preset returns complete -data. +- **CI Failure Rate**: the share of queue CI runs that failed. A rising rate + usually means flaky tests, unstable CI, or problematic changes being queued. + +- **Batch Bisection Count**: how often Mergify had to split a failing batch to + find the culprit. A high count means batches are failing often. + +### Throughput + +Volume of pull requests processed and queue capacity. + +- **Entered PRs** and **Merged PRs**: how many pull requests joined and left the + queue over time. A consistent trend indicates a stable development + environment; sudden drops or spikes are worth investigating. + +- **Max Queue Size**: the largest the queue got. The reference line marks your + max checks capacity (max batch size × + [`max_parallel_checks`](/merge-queue/performance#parallel-checks)), so a queue + above the line means pull requests are waiting for a free check slot. + +- **Average Batch Size**: the reference line shows the largest + [`batch_size`](/merge-queue/batches) configured across your queue rules. Sitting + at the maximum suggests the queue is saturated. + +- **Max Running Checks**: peak concurrent checks. If you are often at capacity, + raising `max_parallel_checks` improves throughput. + +### Performance + +Queue timing and CI execution speed. + +- **Time Breakdown**: how a pull request's time in queue splits across waiting + for CI capacity, [schedule](/configuration/data-types#schedule) windows, + [freeze](/merge-protections/freeze) periods, and CI runtime. Switch each + component between **Avg**, **P95**, and **Max** to see whether the queue is + usually fast with rare spikes or consistently slow. Only the average is + additive, so the total in the center is shown for **Avg** only. If capacity + wait dominates, raise `max_parallel_checks`. + +- **Average Queue Time**: the full time a pull request spent in the queue. + +- **Average CI Runtime**: how long your CI takes. An increase here slows the + whole queue down. + +- **Batches Saved**: batches that merged without running their own speculative + checks, because a later batch containing their changes had already passed. Each + one is a CI run the queue avoided. This requires + [`skip_intermediate_results`](/merge-queue/batches#skip-intermediate-results-anti-flake-protection) + on the queue. ## Monitoring the Queue with the CLI