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 new file mode 100644 index 000000000000000..9201b16ddd3f128 --- /dev/null +++ b/src/content/changelog/queues/2026-04-15-improved-queues-metrics.mdx @@ -0,0 +1,35 @@ +--- +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-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_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: + +- `/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 { + 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. + +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..d15afd27d311128 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