From e0f938f3288f0b9a9547f4ac2a3e50ada48ea9f9 Mon Sep 17 00:00:00 2001 From: mmalden Date: Fri, 10 Apr 2026 15:45:43 -0400 Subject: [PATCH 1/6] [Queues] Add realtime backlog metrics changelog and documentation --- .../2026-04-10-improved-queues-metrics.mdx | 33 ++++++++++ .../queues/configuration/javascript-apis.mdx | 63 +++++++++++++++++-- .../docs/queues/observability/metrics.mdx | 14 +++++ 3 files changed, 106 insertions(+), 4 deletions(-) create mode 100644 src/content/changelog/queues/2026-04-10-improved-queues-metrics.mdx diff --git a/src/content/changelog/queues/2026-04-10-improved-queues-metrics.mdx b/src/content/changelog/queues/2026-04-10-improved-queues-metrics.mdx new file mode 100644 index 000000000000000..750732c0ef64d2e --- /dev/null +++ b/src/content/changelog/queues/2026-04-10-improved-queues-metrics.mdx @@ -0,0 +1,33 @@ +--- +title: Realtime backlog metrics now available for Queues +description: Cloudflare Queues metrics now include realtime backlog size (in count & bytes) and oldest message timestamp +products: + - queues +date: 2026-04-10 +--- + +[Queues](/queues/), Cloudflare's managed message queue, now exposes realtime backlog metrics via the dashboard, REST API, and JavaScript API. Three new fields are available: + +- **`backlog_count`** — the number of unacknowledged messages in the queue +- **`backlog_bytes`** — the total size of those messages in bytes +- **`oldest_message_timestamp`** — the timestamp of the oldest unacknowledged message, useful for calculating how far behind your consumers are + +The following endpoints also now include a `metadata.metrics` object on the result field after successful message consumption: + +- `/accounts/{account_id}/queues/{queue_id}/messages/pull` +- `/accounts/{account_id}/queues/{queue_id}/messages` +- `/accounts/{account_id}/queues/{queue_id}/messages/batch` + +### Javascript APIs + +Call `env.QUEUE.metrics()` to get realtime backlog metrics: + +```ts +const metrics = await env.QUEUE.metrics(); +metrics.backlogCount; // number +metrics.backlogBytes; // number +metrics.oldestMessageTimestamp; // number (milliseconds since epoch) + +`env.QUEUE.send()` and `env.QUEUE.sendBatch()` also now return a metrics object on the response. + +You can also query these fields via the [GraphQL Analytics API](/analytics/graphql-api/). For more information, refer to [Metrics](/queues/observability/metrics/). diff --git a/src/content/docs/queues/configuration/javascript-apis.mdx b/src/content/docs/queues/configuration/javascript-apis.mdx index 15446ad58f0f2b8..8608093141270c9 100644 --- a/src/content/docs/queues/configuration/javascript-apis.mdx +++ b/src/content/docs/queues/configuration/javascript-apis.mdx @@ -92,24 +92,29 @@ A binding that allows a producer to send messages to a Queue. ```ts interface Queue { - send(body: Body, options?: QueueSendOptions): Promise; - sendBatch(messages: Iterable>, options?: QueueSendBatchOptions): Promise; + send(body: Body, options?: QueueSendOptions): Promise; + sendBatch(messages: Iterable>, options?: QueueSendBatchOptions): Promise; + metrics(): Promise; } ``` -* `send(bodyunknown, options?{ contentType?: QueuesContentType })` +* `send(body: unknown, options?: {contentType?: QueuesContentType }) /> * Sends a message to the Queue. The body can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types), as long as its size is less than 128 KB. * When the promise resolves, the message is confirmed to be written to disk. + * Returns a [QueueSendResult](#queuesendresult) containing realtime metrics about the queue. -* `sendBatch(messagesIterable>, options?QueueSendBatchOptions)` +* `sendBatch(messages: Iterable>, options?: QueueSendBatchOptions) /> * Sends a batch of messages to the Queue. Each item in the provided [Iterable](https://www.typescriptlang.org/docs/handbook/iterators-and-generators.html) must be supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types). A batch can contain up to 100 messages, though items are limited to 128 KB each, and the total size of the array cannot exceed 256 KB. * The optional `options` parameter can be used to apply settings (such as `delaySeconds`) to all messages in the batch. See [QueueSendBatchOptions](#queuesendbatchoptions). * When the promise resolves, the messages are confirmed to be written to disk. +* `metrics()` + + * Returns realtime [QueueMetrics](#queuemetrics) for the queue. ### `MessageSendRequest` @@ -191,6 +196,54 @@ The default content type for Queues changed to `json` (from `v8`) to improve com If you specify an invalid content type, or if your specified content type does not match the message content's type, the send operation will fail with an error. +### `QueueSendResult` + +The result of a successful send operation. + +```ts +interface QueueSendResult { + metadata: { + metrics: QueueMetrics; + }; +} +``` + + + +* metadata + + * Contains metadata about the queue after the send operation. + +* metadata.metrics + + * Realtime metrics for the queue. See [QueueMetrics](#queuemetrics). + +### `QueueMetrics` + +Realtime metrics for a queue. + +```ts +interface QueueMetrics { + backlogCount: number; + backlogBytes: number; + oldestMessageTimestamp: number; +} +``` + + + +* backlogCount + + * The number of messages currently in the queue. + +* backlogBytes + + * The total size of messages in the queue, in bytes. + +* oldestMessageTimestamp + + * The timestamp (in milliseconds since epoch) of the oldest message in the queue. + ## Consumer These APIs allow a consumer Worker to consume messages from a Queue. @@ -355,3 +408,5 @@ interface QueueRetryOptions { * The number of seconds to [delay a message](/queues/configuration/batching-retries/) for within the queue, before it can be delivered to a consumer. * Must be a positive integer. +* When the promise resolves, the messages are confirmed to be written to disk. + * Returns a [QueueSendResult](#queuesendresult) containing realtime metrics about the queue. diff --git a/src/content/docs/queues/observability/metrics.mdx b/src/content/docs/queues/observability/metrics.mdx index dfa7cf8717e86b0..be129f8daaa75eb 100644 --- a/src/content/docs/queues/observability/metrics.mdx +++ b/src/content/docs/queues/observability/metrics.mdx @@ -67,6 +67,20 @@ The `queueMessageOperationsAdaptiveGroups` dataset provides the following dimens - `datetimeHour` - Timestamp for the message operation, truncated to the start of an hour - `datetimeMinute` - Timestamp for the message operation, truncated to the start of a minute +### Realtime backlog + +You can access realtime backlog metrics via the [Queues REST API](/api/resources/queues/) and [JavaScript API](/queues/configuration/javascript-apis/). These metrics provide point-in-time values rather than aggregated data. + +| Metric | Field Name | Description | +| ------------------------ | -------------------------- | -------------------------------------------------------------- | +| Backlog count | `backlog_count` | Number of messages currently in the queue | +| Backlog bytes | `backlog_bytes` | Total size of messages in the queue, in bytes | +| Oldest message timestamp | `oldest_message_timestamp_ms` | Timestamp (in milliseconds) of the oldest message in the queue | + +To retrieve these metrics via the REST API, use the metrics endpoint (`/accounts/{account_id}/queues/{queue_id}/metrics`). + +These fields are also included in `metadata.metrics` when calling `send()`, `sendBatch()`, or `metrics()` via the JavaScript API. + ## Example GraphQL Queries ### Get average queue backlog over time period From 5a69b8cc10ea9b626c88d7b21799de47241ad101 Mon Sep 17 00:00:00 2001 From: mia303 Date: Fri, 10 Apr 2026 15:55:19 -0400 Subject: [PATCH 2/6] Update 2026-04-10-improved-queues-metrics.mdx --- .../changelog/queues/2026-04-10-improved-queues-metrics.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/changelog/queues/2026-04-10-improved-queues-metrics.mdx b/src/content/changelog/queues/2026-04-10-improved-queues-metrics.mdx index 750732c0ef64d2e..5c4abc0aa9ea52d 100644 --- a/src/content/changelog/queues/2026-04-10-improved-queues-metrics.mdx +++ b/src/content/changelog/queues/2026-04-10-improved-queues-metrics.mdx @@ -27,6 +27,7 @@ const metrics = await env.QUEUE.metrics(); metrics.backlogCount; // number metrics.backlogBytes; // number metrics.oldestMessageTimestamp; // number (milliseconds since epoch) +``` `env.QUEUE.send()` and `env.QUEUE.sendBatch()` also now return a metrics object on the response. From 05937372f557855adff76a96b94f8c3730657882 Mon Sep 17 00:00:00 2001 From: mia303 Date: Tue, 14 Apr 2026 09:45:54 -0400 Subject: [PATCH 3/6] Update and rename 2026-04-10-improved-queues-metrics.mdx to 2026-04-15-improved-queues-metrics.mdx --- ...s.mdx => 2026-04-15-improved-queues-metrics.mdx} | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) rename src/content/changelog/queues/{2026-04-10-improved-queues-metrics.mdx => 2026-04-15-improved-queues-metrics.mdx} (77%) diff --git a/src/content/changelog/queues/2026-04-10-improved-queues-metrics.mdx b/src/content/changelog/queues/2026-04-15-improved-queues-metrics.mdx similarity index 77% rename from src/content/changelog/queues/2026-04-10-improved-queues-metrics.mdx rename to src/content/changelog/queues/2026-04-15-improved-queues-metrics.mdx index 5c4abc0aa9ea52d..fdf3baacf23d044 100644 --- a/src/content/changelog/queues/2026-04-10-improved-queues-metrics.mdx +++ b/src/content/changelog/queues/2026-04-15-improved-queues-metrics.mdx @@ -3,14 +3,14 @@ title: Realtime backlog metrics now available for Queues description: Cloudflare Queues metrics now include realtime backlog size (in count & bytes) and oldest message timestamp products: - queues -date: 2026-04-10 +date: 2026-04-15 --- [Queues](/queues/), Cloudflare's managed message queue, now exposes realtime backlog metrics via the dashboard, REST API, and JavaScript API. Three new fields are available: - **`backlog_count`** — the number of unacknowledged messages in the queue - **`backlog_bytes`** — the total size of those messages in bytes -- **`oldest_message_timestamp`** — the timestamp of the oldest unacknowledged message, useful for calculating how far behind your consumers are +- **`oldest_message_timestamp_ms`** — the timestamp of the oldest unacknowledged message, useful for calculating how far behind your consumers are The following endpoints also now include a `metadata.metrics` object on the result field after successful message consumption: @@ -23,10 +23,11 @@ The following endpoints also now include a `metadata.metrics` object on the resu Call `env.QUEUE.metrics()` to get realtime backlog metrics: ```ts -const metrics = await env.QUEUE.metrics(); -metrics.backlogCount; // number -metrics.backlogBytes; // number -metrics.oldestMessageTimestamp; // number (milliseconds since epoch) +const { + backlogCount, // number + backlogBytes, // number + oldestMessageTimestamp, // Date | undefined +} = await env.QUEUE.metrics() ``` `env.QUEUE.send()` and `env.QUEUE.sendBatch()` also now return a metrics object on the response. From 82a627d098ec3f22aed2dbf227f8da9c7352c2eb Mon Sep 17 00:00:00 2001 From: mmalden Date: Tue, 14 Apr 2026 10:02:07 -0400 Subject: [PATCH 4/6] fix-build --- src/content/docs/queues/configuration/javascript-apis.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/queues/configuration/javascript-apis.mdx b/src/content/docs/queues/configuration/javascript-apis.mdx index 8608093141270c9..f595cb39ef5561d 100644 --- a/src/content/docs/queues/configuration/javascript-apis.mdx +++ b/src/content/docs/queues/configuration/javascript-apis.mdx @@ -100,13 +100,13 @@ interface Queue { -* `send(body: unknown, options?: {contentType?: QueuesContentType }) /> +* `send(body: unknown, options?: {contentType?: QueuesContentType })` * Sends a message to the Queue. The body can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types), as long as its size is less than 128 KB. * When the promise resolves, the message is confirmed to be written to disk. * Returns a [QueueSendResult](#queuesendresult) containing realtime metrics about the queue. -* `sendBatch(messages: Iterable>, options?: QueueSendBatchOptions) /> +* `sendBatch(messages: Iterable>, options?: QueueSendBatchOptions)` * Sends a batch of messages to the Queue. Each item in the provided [Iterable](https://www.typescriptlang.org/docs/handbook/iterators-and-generators.html) must be supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types). A batch can contain up to 100 messages, though items are limited to 128 KB each, and the total size of the array cannot exceed 256 KB. * The optional `options` parameter can be used to apply settings (such as `delaySeconds`) to all messages in the batch. See [QueueSendBatchOptions](#queuesendbatchoptions). From dc78ac2c3eb73cfdd8703090d1d72fcc2624c72d Mon Sep 17 00:00:00 2001 From: mia303 Date: Tue, 14 Apr 2026 10:56:27 -0400 Subject: [PATCH 5/6] Update javascript-apis.mdx --- src/content/docs/queues/configuration/javascript-apis.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/queues/configuration/javascript-apis.mdx b/src/content/docs/queues/configuration/javascript-apis.mdx index f595cb39ef5561d..d15afd27d311128 100644 --- a/src/content/docs/queues/configuration/javascript-apis.mdx +++ b/src/content/docs/queues/configuration/javascript-apis.mdx @@ -106,7 +106,7 @@ interface Queue { * When the promise resolves, the message is confirmed to be written to disk. * Returns a [QueueSendResult](#queuesendresult) containing realtime metrics about the queue. -* `sendBatch(messages: Iterable>, options?: QueueSendBatchOptions)` +* `sendBatch(messages: Iterable>, options?: QueueSendBatchOptions)` * Sends a batch of messages to the Queue. Each item in the provided [Iterable](https://www.typescriptlang.org/docs/handbook/iterators-and-generators.html) must be supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types). A batch can contain up to 100 messages, though items are limited to 128 KB each, and the total size of the array cannot exceed 256 KB. * The optional `options` parameter can be used to apply settings (such as `delaySeconds`) to all messages in the batch. See [QueueSendBatchOptions](#queuesendbatchoptions). From 5f410d5a368f32af3f3db4863144e91a2f05061f Mon Sep 17 00:00:00 2001 From: mia303 Date: Tue, 14 Apr 2026 12:58:13 -0400 Subject: [PATCH 6/6] Update 2026-04-15-improved-queues-metrics.mdx --- .../changelog/queues/2026-04-15-improved-queues-metrics.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/changelog/queues/2026-04-15-improved-queues-metrics.mdx b/src/content/changelog/queues/2026-04-15-improved-queues-metrics.mdx index fdf3baacf23d044..9201b16ddd3f128 100644 --- a/src/content/changelog/queues/2026-04-15-improved-queues-metrics.mdx +++ b/src/content/changelog/queues/2026-04-15-improved-queues-metrics.mdx @@ -10,7 +10,7 @@ date: 2026-04-15 - **`backlog_count`** — the number of unacknowledged messages in the queue - **`backlog_bytes`** — the total size of those messages in bytes -- **`oldest_message_timestamp_ms`** — the timestamp of the oldest unacknowledged message, useful for calculating how far behind your consumers are +- **`oldest_message_timestamp_ms`** — the timestamp of the oldest unacknowledged message The following endpoints also now include a `metadata.metrics` object on the result field after successful message consumption: