docs(workers-for-platforms): per-tenant observability with Workers Logs

src/content/docs/cloudflare-for-platforms/workers-for-platforms/configuration/observability.mdx

@@ -10,7 +10,39 @@ 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. They differ in how much of the logging stack Cloudflare runs for you:
+
+- [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
+
+[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:
+
+```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 `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.
 
 ### Workers Trace Events Logpush
 
@@ -29,9 +61,9 @@ 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.
 
-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 +76,27 @@ 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 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 {
+          cpuTimeP50
+          cpuTimeP99
+        }
+      }
+    }
+  }
+}
+```