From 703fc4c4833e09b91e6ae39074673672658761b9 Mon Sep 17 00:00:00 2001 From: Thomas Ankcorn Date: Fri, 14 Aug 2026 16:48:02 +0100 Subject: [PATCH 1/4] docs(workers-for-platforms): document per-tenant observability with Workers Logs --- .../configuration/observability.mdx | 58 ++++++++++++++++++- 1 file changed, 56 insertions(+), 2 deletions(-) diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx index 6a9982c4fc0..7e6d81f7e18 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx @@ -10,7 +10,38 @@ Workers for Platforms provides you with logs and analytics that can be used to s ## Logs -Learn how to access logs with Workers for Platforms. +There are a few ways to access logs with Workers for Platforms. For most platforms, [Workers Logs](#workers-logs) is the best starting point: it is a fully managed logging platform, so you get storage, indexing, and a queryable API without building or operating a logging pipeline of your own. Reach for Logpush or Tail Workers when you need to forward logs to your own destination. + +### Workers Logs + +[Workers Logs](/workers/observability/logs/workers-logs/) automatically stores logs from your user Workers in your Cloudflare account, where you can query them with the [Query Builder](/workers/observability/query-builder/) or the [Workers Observability API](/api/resources/workers/subresources/observability/). Because it is fully managed, you can surface a per-user view of logs in your own dashboard without standing up a database, configuring a Logpush destination, or deploying a Tail Worker. + +Enable Workers Logs on a user Worker by including the `observability` setting in the [metadata](/cloudflare-for-platforms/workers-for-platforms/reference/metadata/) when you [upload the script](/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/subresources/content/methods/update/) to your dispatch namespace: + +```json +{ + "main_module": "index.js", + "observability": { + "enabled": true, + "logs": { + "enabled": true, + "invocation_logs": true, + "head_sampling_rate": 1 + } + } +} +``` + +Because you control the upload metadata, you decide whether logging is enabled for each user Worker. Set `head_sampling_rate` to a value between 0 and 1 to log a percentage of requests, or set `observability.enabled` to `false` to turn off collection. + +#### Query logs for a single user Worker + +Workers Logs are stored in the `cloudflare-workers` dataset. When you query the [Workers Observability API](/api/resources/workers/subresources/observability/) on behalf of an end user, scope every query to the specific user Worker so that one tenant cannot read another tenant's telemetry. Filter on the script name your platform assigned to the user Worker in the dispatch namespace: + +- `dataset` — `cloudflare-workers`, the dataset that stores Workers Logs. +- `$metadata.service` — the user Worker's script name. + +Apply these filters on the server using the script name you control, rather than accepting a script name, dataset, or raw filter from the browser. This keeps each user's logs isolated even when the query is triggered by end-user input such as a search term or time range. ### Workers Trace Events Logpush @@ -31,7 +62,7 @@ A [Tail Worker](/workers/observability/logs/tail-workers/) receives information Use [Tail Workers](/workers/observability/logs/tail-workers/) instead of Logpush if you want granular control over formatting before logs are sent to their destination to receive [diagnostics channel events](/workers/runtime-apis/nodejs/diagnostics-channel), or if you want logs delivered in real-time. -Adding a Tail Worker to your dispatch Worker collects logs for both the dispatch Worker and for any user Workers in the dispatch namespace. Logs are automatically collected for all new Workers added to a dispatch namespace. To enable logging for an individual user Worker rather than an entire dispatch namespace, add the [Tail Worker configuration](/workers/observability/logs/tail-workers/#configure-tail-workers) directly to the user Worker. +To collect logs from a user Worker, add the [Tail Worker configuration](/workers/observability/logs/tail-workers/#configure-tail-workers) directly to that user Worker. ## Analytics @@ -44,3 +75,26 @@ There are two ways for you to review your Workers for Platforms analytics. ### GraphQL Analytics API Use Cloudflare’s [GraphQL Analytics API](/analytics/graphql-api) to get metrics relating to your Dispatch Namespaces. Use the `dispatchNamespaceName` dimension in the `workersInvocationsAdaptive` node to query usage by namespace. + +To show metrics for a single user Worker, filter `workersInvocationsAdaptive` by the `scriptName` of that user Worker. This returns request counts, error counts, and CPU or wall time quantiles without requiring Workers Logs to be enabled, so you can display per-user metrics even when log collection is turned off. + +```graphql +query UserWorkerMetrics($accountTag: string!, $scriptName: string!, $start: Time!, $end: Time!) { + viewer { + accounts(filter: { accountTag: $accountTag }) { + workersInvocationsAdaptive( + limit: 1 + filter: { scriptName: $scriptName, datetime_geq: $start, datetime_leq: $end } + ) { + sum { + requests + errors + } + quantiles { + wallTimeP95 + } + } + } + } +} +``` From 9bdc8da9022c9ba395e7a28fe54608b355a1e99f Mon Sep 17 00:00:00 2001 From: Thomas Ankcorn Date: Mon, 17 Aug 2026 11:21:54 +0100 Subject: [PATCH 2/4] docs(workers-for-platforms): fix review nits on observability page Use the standard Upload User Worker API path, documented GraphQL quantile fields, and prose instead of a two-item list. --- .../configuration/observability.mdx | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx index 7e6d81f7e18..3524839c677 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx @@ -16,7 +16,7 @@ There are a few ways to access logs with Workers for Platforms. For most platfor [Workers Logs](/workers/observability/logs/workers-logs/) automatically stores logs from your user Workers in your Cloudflare account, where you can query them with the [Query Builder](/workers/observability/query-builder/) or the [Workers Observability API](/api/resources/workers/subresources/observability/). Because it is fully managed, you can surface a per-user view of logs in your own dashboard without standing up a database, configuring a Logpush destination, or deploying a Tail Worker. -Enable Workers Logs on a user Worker by including the `observability` setting in the [metadata](/cloudflare-for-platforms/workers-for-platforms/reference/metadata/) when you [upload the script](/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/subresources/content/methods/update/) to your dispatch namespace: +Enable Workers Logs on a user Worker by including the `observability` setting in the [metadata](/cloudflare-for-platforms/workers-for-platforms/reference/metadata/) when you [upload the script](/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/methods/update/) to your dispatch namespace: ```json { @@ -36,10 +36,7 @@ Because you control the upload metadata, you decide whether logging is enabled f #### Query logs for a single user Worker -Workers Logs are stored in the `cloudflare-workers` dataset. When you query the [Workers Observability API](/api/resources/workers/subresources/observability/) on behalf of an end user, scope every query to the specific user Worker so that one tenant cannot read another tenant's telemetry. Filter on the script name your platform assigned to the user Worker in the dispatch namespace: - -- `dataset` — `cloudflare-workers`, the dataset that stores Workers Logs. -- `$metadata.service` — the user Worker's script name. +Workers Logs are stored in the `cloudflare-workers` dataset. When you query the [Workers Observability API](/api/resources/workers/subresources/observability/) on behalf of an end user, scope every query to the specific user Worker so that one tenant cannot read another tenant's telemetry. Filter on `dataset` (set to `cloudflare-workers`) and `$metadata.service` (the user Worker's script name). Apply these filters on the server using the script name you control, rather than accepting a script name, dataset, or raw filter from the browser. This keeps each user's logs isolated even when the query is triggered by end-user input such as a search term or time range. @@ -76,7 +73,7 @@ There are two ways for you to review your Workers for Platforms analytics. Use Cloudflare’s [GraphQL Analytics API](/analytics/graphql-api) to get metrics relating to your Dispatch Namespaces. Use the `dispatchNamespaceName` dimension in the `workersInvocationsAdaptive` node to query usage by namespace. -To show metrics for a single user Worker, filter `workersInvocationsAdaptive` by the `scriptName` of that user Worker. This returns request counts, error counts, and CPU or wall time quantiles without requiring Workers Logs to be enabled, so you can display per-user metrics even when log collection is turned off. +To show metrics for a single user Worker, filter `workersInvocationsAdaptive` by the `scriptName` of that user Worker. This returns request counts, error counts, and CPU time quantiles without requiring Workers Logs to be enabled, so you can display per-user metrics even when log collection is turned off. ```graphql query UserWorkerMetrics($accountTag: string!, $scriptName: string!, $start: Time!, $end: Time!) { @@ -91,7 +88,8 @@ query UserWorkerMetrics($accountTag: string!, $scriptName: string!, $start: Time errors } quantiles { - wallTimeP95 + cpuTimeP50 + cpuTimeP99 } } } From f4d73f10b63cf27d99bb49acd62c37077c650fdb Mon Sep 17 00:00:00 2001 From: Thomas Ankcorn Date: Tue, 18 Aug 2026 09:59:37 +0100 Subject: [PATCH 3/4] docs(workers-for-platforms): clarify who runs pipeline vs storage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Avoid "destination" — it collides with Observability destinations. --- .../configuration/observability.mdx | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx index 3524839c677..5b47efc7c1f 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx @@ -10,11 +10,15 @@ Workers for Platforms provides you with logs and analytics that can be used to s ## Logs -There are a few ways to access logs with Workers for Platforms. For most platforms, [Workers Logs](#workers-logs) is the best starting point: it is a fully managed logging platform, so you get storage, indexing, and a queryable API without building or operating a logging pipeline of your own. Reach for Logpush or Tail Workers when you need to forward logs to your own destination. +There are a few ways to access logs with Workers for Platforms. They differ in how much of the logging stack Cloudflare runs for you: + +- [Workers Logs](#workers-logs) — Cloudflare collects, stores, and indexes the logs. Query them with the API. This is the best starting point for most platforms. +- [Logpush](#workers-trace-events-logpush) — Cloudflare collects the logs and delivers them; you store them. +- [Tail Workers](#tail-workers) — you receive the logs as they happen and handle storage yourself. ### Workers Logs -[Workers Logs](/workers/observability/logs/workers-logs/) automatically stores logs from your user Workers in your Cloudflare account, where you can query them with the [Query Builder](/workers/observability/query-builder/) or the [Workers Observability API](/api/resources/workers/subresources/observability/). Because it is fully managed, you can surface a per-user view of logs in your own dashboard without standing up a database, configuring a Logpush destination, or deploying a Tail Worker. +[Workers Logs](/workers/observability/logs/workers-logs/) automatically stores logs from your user Workers in your Cloudflare account, where you can query them with the [Query Builder](/workers/observability/query-builder/) or the [Workers Observability API](/api/resources/workers/subresources/observability/). Because it is fully managed, you can surface a per-user view of logs in your own dashboard without standing up a database, setting up Logpush, or deploying a Tail Worker. Enable Workers Logs on a user Worker by including the `observability` setting in the [metadata](/cloudflare-for-platforms/workers-for-platforms/reference/metadata/) when you [upload the script](/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/methods/update/) to your dispatch namespace: @@ -57,7 +61,7 @@ All logs are forwarded to the Logpush job that you have setup for your account. A [Tail Worker](/workers/observability/logs/tail-workers/) receives information about the execution of other Workers (known as producer Workers), such as HTTP statuses, data passed to `console.log()` or uncaught exceptions. -Use [Tail Workers](/workers/observability/logs/tail-workers/) instead of Logpush if you want granular control over formatting before logs are sent to their destination to receive [diagnostics channel events](/workers/runtime-apis/nodejs/diagnostics-channel), or if you want logs delivered in real-time. +Use [Tail Workers](/workers/observability/logs/tail-workers/) instead of Logpush if you want to format logs before they leave Cloudflare, receive [diagnostics channel events](/workers/runtime-apis/nodejs/diagnostics-channel), or get logs in real time. To collect logs from a user Worker, add the [Tail Worker configuration](/workers/observability/logs/tail-workers/#configure-tail-workers) directly to that user Worker. From 6c2deeae4d49e1e6926d80ff646423e5568e87b2 Mon Sep 17 00:00:00 2001 From: Thomas Ankcorn Date: Tue, 18 Aug 2026 10:11:20 +0100 Subject: [PATCH 4/4] docs(workers-for-platforms): parallel copy for the three logging options --- .../workers-for-platforms/configuration/observability.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx index 5b47efc7c1f..5af9ebfa3cc 100644 --- a/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx +++ b/src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx @@ -12,9 +12,9 @@ Workers for Platforms provides you with logs and analytics that can be used to s There are a few ways to access logs with Workers for Platforms. They differ in how much of the logging stack Cloudflare runs for you: -- [Workers Logs](#workers-logs) — Cloudflare collects, stores, and indexes the logs. Query them with the API. This is the best starting point for most platforms. -- [Logpush](#workers-trace-events-logpush) — Cloudflare collects the logs and delivers them; you store them. -- [Tail Workers](#tail-workers) — you receive the logs as they happen and handle storage yourself. +- [Workers Logs](#workers-logs) — Cloudflare stores and indexes your logs, and you query them through the API. Nothing else to run. This is the best starting point for most platforms. +- [Logpush](#workers-trace-events-logpush) — Cloudflare delivers your logs to a storage destination that you own and manage. +- [Tail Workers](#tail-workers) — Cloudflare streams your logs to a Worker in real time, and you decide what to do with them. ### Workers Logs