Using Datadog with Mergify

The Datadog integration pushes your merge queue metrics into your own Datadog account. Everything on the merge queue statistics page is available as a Datadog metric, so you can graph queue health next to your own service metrics and alert on it.

The integration is official and ships as a Mergify tile in Datadog’s integration catalog. Mergify writes the metrics to Datadog for you. There is no agent to install and nothing to run in your CI.

• A Datadog account, and permission to authorize integrations in it.

• On the Mergify side, a plan that includes the Datadog integration, plus the GitHub organization Owner role or the Integrations Admin delegated role.

1. In the Mergify dashboard, go to Integrations → Datadog. Installing the Mergify tile from Datadog’s integration catalog and clicking Connect Accounts lands in the same place.

   

2. Connect your Datadog account. Pick the Datadog site your organization uses (US1, US3, US5, EU1, US1-FED, or AP1), then authorize Mergify. Mergify creates an API key scoped to the integration and starts pushing metrics to that site.

3. Choose what to monitor. For each repository, select the merge queue base branches you want metrics for: the branches your queued pull requests target, such as main or a release branch.

Every metric is published every 5 minutes, and each point covers the 5-minute window it represents.

Every metric carries these tags:

Metrics submitted as count are event tallies that Datadog sums exactly over any time range. Metrics submitted as gauge are peak values within the window.

Both outcome and exit_reason are success when the pull request merged or its checks passed. Otherwise they name the reason the pull request left the queue or its checks were aborted, such as checks_failed or pr_dequeued. The integration’s README lists every value.

The duration and size metrics ship as a .sum and a .count rather than a pre-computed average, so Datadog can recompute the real average over whatever time range you graph. Divide a family’s own sum by its own count:

sum:mergify.queue.total_queue_time.sum{$repository} / sum:mergify.queue.total_queue_time.count{$repository}

The same shape gives you average CI runtime (mergify.queue.ci_runtime.*) and average batch size (mergify.queue.batch_size.*).

The share of failed checks that passed when retried:

sum:mergify.queue.checks_retries.recovered{$repository} / (sum:mergify.queue.checks_retries.recovered{$repository} + sum:mergify.queue.checks_retries.not_recovered{$repository})

Total queued time splits into CI runtime plus three kinds of waiting:

mergify.queue.breakdown.ci_runtime.sum   # running CI
mergify.queue.idle.capacity.sum          # waiting for a free check slot
mergify.queue.idle.schedule.sum          # waiting for a schedule to open
mergify.queue.idle.freeze.sum            # waiting for a freeze to lift

Graphed together as a stacked area, they show what your queue is actually waiting on. Divide any of them by mergify.queue.idle.count for a per-pull-request average.

Because the three idle.* metrics are pure waiting time, sum:mergify.queue.idle.*.sum gives you total wasted time without counting CI.

The Mergify tile ships a Mergify - Merge Queue Stats dashboard that mirrors the merge queue statistics page. In Datadog, open the Mergify integration page and find it under the Monitoring Resources tab. Clone it to adapt it to your own repositories, or build your own from the metrics above.

Since the metrics are ordinary Datadog metrics, you can alert on them with monitors. Useful ones to start with:

• mergify.queue.size.max staying above a threshold, which usually means CI capacity is the bottleneck.

• Average queued time trending up week over week.

• Check retry recovery rate dropping, which points at genuinely broken tests rather than flaky ones.

• mergify.queue.exit_reason counting anything other than success, which means pull requests are leaving the queue without merging.

• Monitoring your merge queue: what each metric means and how to read it.

• The Mergify tile on Datadog: setup from the Datadog side and the bundled dashboard.