Observability

Workers for Platforms provides you with logs and analytics that can be used to share data with end users.

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 — 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 — Cloudflare delivers your logs to a storage destination that you own and manage.
• Tail Workers — Cloudflare streams your logs to a Worker in real time, and you decide what to do with them.

Workers Logs automatically stores logs from your user Workers in your Cloudflare account, where you can query them with the Query Builder or the Workers Observability API. 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 when you upload the script to your dispatch namespace:

{
	"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.

Workers Logs are stored in the cloudflare-workers dataset. When you query the Workers Observability API 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 is used to get raw Workers execution logs. Refer to Logpush for more information.

Logpush can be enabled for an entire dispatch namespace or a single user Worker. To capture logs for all of the user Workers in a dispatch namespace:

1. Create a Logpush job.
2. Enable logging on your dispatch Worker.

Enabling logging on 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, skip step 1 and complete step 2 on your user Worker.

All logs are forwarded to the Logpush job that you have setup for your account. Logpush filters can be used on the Outcome or Script Name field to include or exclude specific values or send logs to different destinations.

A Tail Worker 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 instead of Logpush if you want to format logs before they leave Cloudflare, receive diagnostics channel events, or get logs in real time.

To collect logs from a user Worker, add the Tail Worker configuration directly to that user Worker.

There are two ways for you to review your Workers for Platforms analytics.

Workers Analytics Engine can be used with Workers for Platforms to provide analytics to end users. It can be used to expose events relating to a Workers invocation or custom user-defined events. Platforms can write/query events by script tag to get aggregates over a user’s usage.

Use Cloudflare’s GraphQL Analytics 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.

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
        }
      }
    }
  }
}