Skip to content

Commit e0f938f

Browse files
mia303mia303
committed
[Queues] Add realtime backlog metrics changelog and documentation
1 parent 62758f7 commit e0f938f

File tree

3 files changed

+106
-4
lines changed

3 files changed

+106
-4
lines changed

‎src/content/changelog/queues/2026-04-10-improved-queues-metrics.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: Realtime backlog metrics now available for Queues
3+
description: Cloudflare Queues metrics now include realtime backlog size (in count & bytes) and oldest message timestamp
4+
products:
5+
- queues
6+
date: 2026-04-10
7+
---
8+
9+
[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:
10+
11+
- **`backlog_count`** — the number of unacknowledged messages in the queue
12+
- **`backlog_bytes`** — the total size of those messages in bytes
13+
- **`oldest_message_timestamp`** — the timestamp of the oldest unacknowledged message, useful for calculating how far behind your consumers are
14+
15+
The following endpoints also now include a `metadata.metrics` object on the result field after successful message consumption:
16+
17+
- `/accounts/{account_id}/queues/{queue_id}/messages/pull`
18+
- `/accounts/{account_id}/queues/{queue_id}/messages`
19+
- `/accounts/{account_id}/queues/{queue_id}/messages/batch`
20+
21+
### Javascript APIs
22+
23+
Call `env.QUEUE.metrics()` to get realtime backlog metrics:
24+
25+
```ts
26+
const metrics = await env.QUEUE.metrics();
27+
metrics.backlogCount; // number
28+
metrics.backlogBytes; // number
29+
metrics.oldestMessageTimestamp; // number (milliseconds since epoch)
30+
31+
`env.QUEUE.send()` and `env.QUEUE.sendBatch()` also now return a metrics object on the response.
32+
33+
You can also query these fields via the [GraphQL Analytics API](/analytics/graphql-api/). For more information, refer to [Metrics](/queues/observability/metrics/).

‎src/content/docs/queues/configuration/javascript-apis.mdx‎

Lines changed: 59 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -92,24 +92,29 @@ A binding that allows a producer to send messages to a Queue.
9292

9393
```ts
9494
interface Queue<Body = unknown> {
95-
send(body: Body, options?: QueueSendOptions): Promise<void>;
96-
sendBatch(messages: Iterable<MessageSendRequest<Body>>, options?: QueueSendBatchOptions): Promise<void>;
95+
send(body: Body, options?: QueueSendOptions): Promise<QueueSendResult>;
96+
sendBatch(messages: Iterable<MessageSendRequest<Body>>, options?: QueueSendBatchOptions): Promise<QueueSendResult>;
97+
metrics(): Promise<QueueMetrics>;
9798
}
9899
```
99100

100101

101102

102-
* `send(bodyunknown, options?{ contentType?: QueuesContentType })` <Type text="Promise<void>" />
103+
* `send(body: unknown, options?: {contentType?: QueuesContentType }) />
103104

104105
* 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.
105106
* When the promise resolves, the message is confirmed to be written to disk.
107+
* Returns a [QueueSendResult](#queuesendresult) containing realtime metrics about the queue.
106108

107-
* `sendBatch(messagesIterable<MessageSendRequest<unknown>>, options?QueueSendBatchOptions)` <Type text="Promise<void>" />
109+
* `sendBatch(messages: Iterable<MessageSendRequest<unknown>>, options?: QueueSendBatchOptions) />
108110

109111
* 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.
110112
* The optional `options` parameter can be used to apply settings (such as `delaySeconds`) to all messages in the batch. See [QueueSendBatchOptions](#queuesendbatchoptions).
111113
* When the promise resolves, the messages are confirmed to be written to disk.
112114

115+
* `metrics()` <Type text="Promise<QueueMetrics>" />
116+
117+
* Returns realtime [QueueMetrics](#queuemetrics) for the queue.
113118

114119

115120
### `MessageSendRequest`
@@ -191,6 +196,54 @@ The default content type for Queues changed to `json` (from `v8`) to improve com
191196

192197
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.
193198

199+
### `QueueSendResult`
200+
201+
The result of a successful send operation.
202+
203+
```ts
204+
interface QueueSendResult {
205+
metadata: {
206+
metrics: QueueMetrics;
207+
};
208+
}
209+
```
210+
211+
212+
213+
* <code>metadata</code> <Type text="object" />
214+
215+
* Contains metadata about the queue after the send operation.
216+
217+
* <code>metadata.metrics</code> <Type text="QueueMetrics" />
218+
219+
* Realtime metrics for the queue. See [QueueMetrics](#queuemetrics).
220+
221+
### `QueueMetrics`
222+
223+
Realtime metrics for a queue.
224+
225+
```ts
226+
interface QueueMetrics {
227+
backlogCount: number;
228+
backlogBytes: number;
229+
oldestMessageTimestamp: number;
230+
}
231+
```
232+
233+
234+
235+
* <code>backlogCount</code> <Type text="number" />
236+
237+
* The number of messages currently in the queue.
238+
239+
* <code>backlogBytes</code> <Type text="number" />
240+
241+
* The total size of messages in the queue, in bytes.
242+
243+
* <code>oldestMessageTimestamp</code> <Type text="number" />
244+
245+
* The timestamp (in milliseconds since epoch) of the oldest message in the queue.
246+
194247
## Consumer
195248

196249
These APIs allow a consumer Worker to consume messages from a Queue.
@@ -355,3 +408,5 @@ interface QueueRetryOptions {
355408

356409
* The number of seconds to [delay a message](/queues/configuration/batching-retries/) for within the queue, before it can be delivered to a consumer.
357410
* Must be a positive integer.
411+
* When the promise resolves, the messages are confirmed to be written to disk.
412+
* Returns a [QueueSendResult](#queuesendresult) containing realtime metrics about the queue.

‎src/content/docs/queues/observability/metrics.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,20 @@ The `queueMessageOperationsAdaptiveGroups` dataset provides the following dimens
6767
- `datetimeHour` - Timestamp for the message operation, truncated to the start of an hour
6868
- `datetimeMinute` - Timestamp for the message operation, truncated to the start of a minute
6969

70+
### Realtime backlog
71+
72+
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.
73+
74+
| Metric | Field Name | Description |
75+
| ------------------------ | -------------------------- | -------------------------------------------------------------- |
76+
| Backlog count | `backlog_count` | Number of messages currently in the queue |
77+
| Backlog bytes | `backlog_bytes` | Total size of messages in the queue, in bytes |
78+
| Oldest message timestamp | `oldest_message_timestamp_ms` | Timestamp (in milliseconds) of the oldest message in the queue |
79+
80+
To retrieve these metrics via the REST API, use the metrics endpoint (`/accounts/{account_id}/queues/{queue_id}/metrics`).
81+
82+
These fields are also included in `metadata.metrics` when calling `send()`, `sendBatch()`, or `metrics()` via the JavaScript API.
83+
7084
## Example GraphQL Queries
7185

7286
### Get average queue backlog over time period

0 commit comments

Comments
 (0)