Skip to content

docs: update hyperdrive observability metrics documentation #31729

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ivoryibu wants to merge 1 commit into
base: production
Choose a base branch
from
+27 −9
Draft

docs: update hyperdrive observability metrics documentation #31729

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 27 additions & 9 deletions src/content/docs/hyperdrive/observability/metrics.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,16 +36,30 @@ The `volatile` cache status indicates the query contains a PostgreSQL function c

The `hyperdrivePoolSizesAdaptiveGroups` dataset contains the following connection pool metrics:

| Metric | GraphQL Field Name | Description |
| ---------------------- | ----------------------- | ------------------------------------------------------------------------- |
| Avg. open connections | `avg.currentPoolSize` | Average number of connections currently open in the pool. |
| Avg. available slots | `avg.availablePoolSlots`| Average number of pool connections available for checkout. |
| Avg. waiting clients | `avg.waitingClients` | Average number of clients waiting for a connection from the pool. |
| Pool size maximum | `max.maxPoolSize` | Configured maximum size of the connection pool. |
| Peak open connections | `max.currentPoolSize` | Peak number of connections open in the pool. |
| Peak waiting clients | `max.waitingClients` | Peak number of clients waiting for a connection from the pool. |
| Metric | GraphQL Field Name | Description |
| --------------------- | ------------------------ | ----------------------------------------------------------------- |
| Avg. open connections | `avg.currentPoolSize` | Average number of connections currently open in the pool. |
| Avg. available slots | `avg.availablePoolSlots` | Average number of pool connections available for checkout. |
| Avg. waiting clients | `avg.waitingClients` | Average number of clients waiting for a connection from the pool. |
| Pool size maximum | `max.maxPoolSize` | Configured maximum size of the connection pool. |
| Peak open connections | `max.currentPoolSize` | Peak number of connections open in the pool. |
| Peak waiting clients | `max.waitingClients` | Peak number of clients waiting for a connection from the pool. |

Connection contention appears as a spike in waiting clients, or when open connections consistently approach the pool size maximum. If your open connections regularly approach this limit, consider [increasing your Hyperdrive connection limit](/hyperdrive/platform/limits/#request-a-limit-increase).
#### How Hyperdrive distributes your connection pool

Hyperdrive shards your connection pool across five machines within each Cloudflare location. Your configured maximum is divided evenly across these machines. For example, a connection limit of 100 gives each machine a maximum of 20 connections (100 / 5).

@ask-bonk ask-bonk Bot Jun 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: "divided evenly" implies exact equal distribution for every possible limit. For limits not divisible by 5 (for example, 97), this may not be literally true. Consider softening to "divided across" or adding an "approximately" qualifier.


Each machine starts with an empty pool and reuses open connections. Hyperdrive opens few connections to your origin database, and each pool grows only as concurrent demand requires it.

Pool size metrics currently report per-machine values for each location. They are not aggregated into a single total across all machines and locations. As a result, `max.currentPoolSize` plateaus at the per-machine slice (for example, 20) rather than your full configured maximum (for example, 100), even when the pool is operating normally.

:::note
A spike in waiting clients does not mean clients are stuck waiting. The `waitingClients` metric is a point-in-time count of clients waiting for a connection at the moment each value is recorded. It does not measure how long a client waited, which is typically a few milliseconds.
:::

Connection contention appears as a sustained spike in waiting clients, or when per-machine open connections consistently approach the per-machine slice of your pool size maximum. If your open connections regularly approach this limit, consider [increasing your Hyperdrive connection limit](/hyperdrive/platform/limits/#request-a-limit-increase).

To estimate your total connection usage across a configuration, sum the per-location values returned by the [GraphQL Analytics API](#query-via-the-graphql-api).

@ask-bonk ask-bonk Bot Jun 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: This says to "sum the per-location values," but the GraphQL section clarifies that each returned value is per-machine. This could be misread as summing one value per location. Consider rewording to something like: "To estimate your total connection usage across a configuration, sum all values returned by the GraphQL Analytics API."


Metrics can be queried (and are retained) for the past 31 days.

Expand All @@ -64,12 +78,16 @@ You can optionally select a time window to query. This defaults to the last 24 h

The dashboard includes a **Pool connections** chart, which displays waiting connections, open connections, and the pool size maximum. You can use the location selector to filter by specific Cloudflare locations.

The values shown are per-machine and are not aggregated across all machines in a location. Refer to [How Hyperdrive distributes your connection pool](#how-hyperdrive-distributes-your-connection-pool) to interpret these values.

## Query via the GraphQL API

You can programmatically query analytics for your Hyperdrive configurations via the [GraphQL Analytics API](/analytics/graphql-api/). This API queries the same datasets as the Cloudflare dashboard, and supports GraphQL [introspection](/analytics/graphql-api/features/discovery/introspection/).

Hyperdrive's GraphQL datasets require an `accountTag` filter with your Cloudflare account ID. Hyperdrive exposes the `hyperdriveQueriesAdaptiveGroups` and `hyperdrivePoolSizesAdaptiveGroups` datasets.

The `hyperdrivePoolSizesAdaptiveGroups` dataset reports per-machine values grouped by the `coloCode` dimension, rather than a single aggregated total. To approximate your total connection usage across all locations, sum the values across each `coloCode` group. This remains an estimate, because each value reflects a single machine rather than a location's full pool. Refer to [How Hyperdrive distributes your connection pool](#how-hyperdrive-distributes-your-connection-pool) for details.

@ask-bonk ask-bonk Bot Jun 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: The instruction to "sum the values across each coloCode group" is slightly ambiguous about whether multiple entries per coloCode need to be summed. Consider making it explicit, for example: "To approximate your total connection usage across all locations, sum the values for every entry returned. Each entry reflects a single machine, so you can also group by coloCode first if you need a per-location estimate."


## Write GraphQL queries

Examples of how to explore your Hyperdrive metrics.
Expand Down