diff --git a/src/content/docs/hyperdrive/observability/metrics.mdx b/src/content/docs/hyperdrive/observability/metrics.mdx index 90f73266c4d..22f8af1e2ca 100644 --- a/src/content/docs/hyperdrive/observability/metrics.mdx +++ b/src/content/docs/hyperdrive/observability/metrics.mdx @@ -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). + +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). Metrics can be queried (and are retained) for the past 31 days. @@ -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. + ## Write GraphQL queries Examples of how to explore your Hyperdrive metrics.