---
title: Using Datadog with Mergify
description: Send your merge queue metrics to Datadog to build dashboards, alerts, and reports alongside the rest of your observability data.
---
The Datadog integration pushes your merge queue metrics into your own Datadog
account. Everything on the
[merge queue statistics page](/merge-queue/monitoring) 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](https://docs.datadoghq.com/integrations/mergify_oauth/) 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.
## Prerequisites
- 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](/security#delegated-roles).
## Setting up the integration
1. Install the [Mergify tile](https://docs.datadoghq.com/integrations/mergify_oauth/)
from Datadog's integration catalog and click **Connect Accounts**. The
connection starts on the Datadog side, so the **Connect Your Datadog
Account** button on the Mergify dashboard's
[`Integrations → Datadog`](https://dashboard.mergify.com/integrations/datadog)
page opens Datadog's catalog rather than connecting from Mergify.
2. Authorize Mergify from the
[Datadog site](https://docs.datadoghq.com/getting_started/site/) your
organization uses. Mergify supports US1, US3, US5, EU1, US1-FED, and AP1, and
connects to whichever one you start from. Datadog then asks which GitHub
organization to connect. 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.
:::note
Metrics only cover the repositories and base branches you select here. When
you add a new release branch, add it to this list too, or its queue activity
will be missing from Datadog.
:::
## Changing your Datadog site
To switch the Datadog site your metrics go to, connect Mergify again from the
site you want to move to, whether you are changing region or consolidating on
a different Datadog organization. You do not need to know which site you are
on today: reconnecting replaces the previous connection, whatever it was.
1. Sign in to Datadog on the site you are moving to.
2. In that account, install the [Mergify
tile](https://docs.datadoghq.com/integrations/mergify_oauth/) and click
**Connect Accounts**, exactly as you did when you [first
connected](#setting-up-the-integration). There is no other way in: Mergify
has no control that starts the change, and no API or CLI equivalent.
3. Choose the same GitHub organization as before, and authorize Mergify. The
site you end up on is the one you started from, so there is nothing else to
pick.
The Datadog permissions in [Prerequisites](#prerequisites) apply again here, but
to the Datadog organization you are moving to; the Mergify role requirement is
unchanged.
Metrics start arriving on the new site at the next publication, and the old site
stops receiving new points at the same moment. If you start the authorization
and do not finish it, nothing changes: the previous connection stays in place
until the new one completes.
### What moves with you, and what does not
Your monitored repositories and their base branches are preserved. They belong
to your GitHub organization rather than to the Datadog connection, so you do not
have to select them again.
What stays behind on the old site:
- **The metrics already sent there.** Mergify publishes new points from the
moment you reconnect; it does not copy history to the new site.
- **Anything you built on those metrics.** Dashboards cloned from the Mergify
tile and any monitors you created live in the old Datadog organization.
Recreate them on the new site.
- **The API key Mergify created.** Reconnecting creates a new key on the new
site and does not revoke the old one, so delete it yourself in the old Datadog
organization once the switch is done.
:::note
If Datadog refuses the new key because a Mergify one already exists in that
account, delete that key in Datadog and reconnect: Mergify creates the key it
needs on the next authorization.
[Contact support](/support) if no points appear on the new site after a few
publication cycles.
:::
## Removing the integration
To stop sending metrics without disconnecting anything, remove every repository
from the integration page in the Mergify dashboard. Metrics only cover the
repositories you select, so an empty list stops them. The connection and the API
key stay in place, ready if you add a repository back.
To disconnect entirely, delete the API key Mergify created in your Datadog
organization. Mergify checks that key every minute and drops the connection as
soon as it stops working, so nothing is left behind on either side. This is the
only route that removes both halves, and it is done from Datadog: the Mergify
dashboard has no disconnect control, because deleting the connection there would
leave the API key live in your Datadog account.
Removing the key needs permission to manage API keys in Datadog. If that is
someone else in your organization, ask them to delete it; clearing the
repository list stops the metrics in the meantime.
## Metrics
Every metric is published every 5 minutes, and each point covers the 5-minute
window it represents.
### Tags
Every metric carries these tags:
| Tag | Description |
| --- | --- |
| `repository` | Full repository name, such as `octo/hello-world` |
| `branch` | The base branch the queued pull requests target |
| `queue` | Name of the [queue rule](/merge-queue/rules) |
| `priority_rule` | Name of the matching [priority rule](/merge-queue/priority), when set |
:::caution
Datadog lowercases tag values on ingestion, and collapses each run of
characters outside `a-z 0-9 _ - : . /` into a single underscore. Query
`outcome:success`, not `outcome:SUCCESS`, and expect a queue named
`automated updates` to arrive as `automated_updates`.
:::
### Reference
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.
| Metric | Type | Description |
| --- | --- | --- |
| `mergify.queue.entered` | count | Pull requests that entered the queue |
| `mergify.queue.merged` | count | Pull requests merged out of the queue |
| `mergify.queue.exit_reason` | count | Pull requests that left the queue, tagged with `exit_reason` |
| `mergify.queue.size.max` | gauge | Largest the queue got |
| `mergify.queue.running_checks.max` | gauge | Most checks running at once |
| `mergify.queue.check_outcome` | count | Finished queue checks, tagged with `outcome` |
| `mergify.queue.checks_retries.recovered` | count | Failed checks that passed on retry |
| `mergify.queue.checks_retries.not_recovered` | count | Failed checks that failed again on retry |
| `mergify.queue.bisection.started` | count | [Batch](/merge-queue/batches) bisections started |
| `mergify.queue.skip_intermediate_results.batches_saved` | count | Batches merged without their own checks |
| `mergify.queue.total_queue_time.sum` | count | Total time queued, in seconds |
| `mergify.queue.total_queue_time.count` | count | Queue sessions the sum covers |
| `mergify.queue.ci_runtime.sum` | count | Total CI runtime, in seconds |
| `mergify.queue.ci_runtime.count` | count | CI runs the sum covers |
| `mergify.queue.batch_size.sum` | count | Total pull requests across batches |
| `mergify.queue.batch_size.count` | count | Batches the sum covers |
| `mergify.queue.breakdown.ci_runtime.sum` | count | Queued time spent running CI, in seconds |
| `mergify.queue.idle.capacity.sum` | count | Queued time spent waiting for capacity, in seconds |
| `mergify.queue.idle.schedule.sum` | count | Queued time spent waiting for a schedule, in seconds |
| `mergify.queue.idle.freeze.sum` | count | Queued time waiting on a [freeze](/merge-protections/freeze), in seconds |
| `mergify.queue.idle.count` | count | Queue sessions the breakdown sums cover |
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](https://github.com/DataDog/integrations-extras/blob/master/mergify_oauth/README.md)
lists every value.
`skip_intermediate_results.batches_saved` counts the batches that merged because
a later batch containing their changes had already passed, so each one is a CI
run the queue avoided. It only moves when
[`skip_intermediate_results`](/merge-queue/batches#skip-intermediate-results-anti-flake-protection)
is enabled on the queue.
## Querying the metrics
### Averages
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:
```text
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.*`).
:::caution
Divide each family by its own `.count`. The `idle.*` and `breakdown.*` sums
share the `mergify.queue.idle.count` denominator; `total_queue_time`,
`ci_runtime`, and `batch_size` each have their own. Averaging a pre-averaged
value, or mixing denominators, gives a number that changes with the graph's
rollup interval.
:::
### Check retry recovery rate
The share of failed checks that passed when retried:
```text
sum:mergify.queue.checks_retries.recovered{$repository} / (sum:mergify.queue.checks_retries.recovered{$repository} + sum:mergify.queue.checks_retries.not_recovered{$repository})
```
### Where queued time goes
Total queued time splits into CI runtime plus three kinds of waiting:
```text
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.
## Dashboards and alerts
The [Mergify tile](https://docs.datadoghq.com/integrations/mergify_oauth/) ships
a **Mergify - Merge Queue Stats** dashboard that mirrors the merge queue
statistics page. In Datadog, search for `mergify` in your
account's integration catalog, open the Mergify tile, and find the
dashboard 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.
## Learn more
- [Monitoring your merge queue](/merge-queue/monitoring): what each metric means
and how to read it.
- The [Mergify tile](https://docs.datadoghq.com/integrations/mergify_oauth/) on
Datadog: setup from the Datadog side and the bundled dashboard.