skip to content

How does Workers Trace Events Logpush send a Cloudflare Worker's logs to an outside destination, and what does it truncate?

level: middleimportance: nice to knowfreq 20%

answer

  1. an account job plus a per-Worker flag
  2. the workers_trace_events dataset
  3. Workers Paid only
  4. 16,384 characters for logs and exceptions

basics

~20 s

On Workers Paid, an account-level Logpush job on the workers_trace_events dataset ships events from every Worker set to logpush: true: request metadata, console messages and uncaught exceptions. Logs and exceptions share 16,384 characters; past that they are truncated.

solid answer

~50 s

Workers Trace Events Logpush has two halves. The account owns a **Logpush job** on the `workers_trace_events` dataset, created on the dashboard's Logpush page or through the API, with a destination such as an R2 bucket, chosen fields such as `Outcome`, `Exceptions`, `Logs` and `ScriptName`, and optional filters and a sampling rate. Each Worker opts in with `logpush: true` in its Wrangler file (default `false`), which does not create the job. Creating the job takes a role with Logpush access, such as Administrator or a Log Share role, or a token with Logs Edit permission. The `logs` and `exceptions` fields share a 16,384-character budget, counted in the order exception names, exception messages, then log messages; once it runs out, one message gets a `<<<Logpush: ... truncated>>>` marker and the rest are dropped. As of 2026-10-10 Cloudflare recommends OpenTelemetry export for new integrations.

code

json · 6 lines
json
{
  "name": "orders-api",
  "main": "src/index.js",
  "compatibility_date": "2026-10-10",
  "logpush": true
}

go deeper

for a junior

Recall that Logpush pushes a Worker's trace events to an outside destination, and that a Worker opts in with logpush: true in its Wrangler file.

for a middle

Explain the two halves, an account job on workers_trace_events and the per-Worker flag, plus the plan and permission requirements.

for a senior

Anticipate the 16,384-character budget, its counting order and its markers, and use job filters and sampling to control volume and cost.

for a principal

Choose one export path for the organisation, Logpush, OpenTelemetry export or Tail Workers, based on existing pipelines, retention needs and who owns the job.

## Two halves that must both exist **Logpush** is Cloudflare's service for pushing log datasets to storage or a logging provider. For Workers, the dataset is **Workers Trace Events** (`workers_trace_events`): one record per invocation with request and response metadata, unstructured `console.log()` messages and uncaught exceptions. It is available on the **Workers Paid** plan, and not for zones on the Cloudflare China Network. Getting a Worker's events out takes two separate pieces: - **The job**, owned by the account: which dataset, which destination, which fields, which filter. It is created once. - **The flag**, owned by each Worker: `logpush: true` in the Wrangler file, or **Enable** under the Worker's **Settings > Observability** once a job exists. Its default is `false`. Wrangler's configuration reference for the key notes that it "will not configure a corresponding Logpush job automatically." A flagged Worker with no job sends nothing; a job with no flagged Worker receives nothing. Once both exist, a newly deployed Worker with the flag is picked up by the existing job. The flag is inheritable, so named Wrangler environments use the top-level value unless they set their own. ## Setting it up 1. Check access. Logpush permissions are separate from Workers permissions: Super Administrators, Administrators and the Log Share roles can configure it, or use an account-scoped API token with **Logs Edit**. 2. Create the job: on the dashboard's Logpush page choose a destination and the **Workers trace events** dataset, or call the account `logpush/jobs` API with `"dataset": "workers_trace_events"`, a `destination_conf` (for example an `r2://` bucket path) and `output_options.field_names`. 3. Add `logpush: true` to each Worker that should be exported and deploy it. The job can carry a **filter** and a **sampling rate**. A filter on `Outcome` keeps or excludes invocations by outcome; the documented example excludes `exception` with the `!eq` operator. ## What a record contains | Field | Contents | |---|---| | `ScriptName` | The Worker that ran | | `Outcome` | The invocation outcome, such as `ok` or `exception` | | `Event` | The triggering request or event | | `EventTimestampMs` | When it ran | | `Logs` | `console` messages with their level | | `Exceptions` | Uncaught exceptions with name and message | ## How truncation works The `logs` and `exceptions` fields share a combined budget of **16,384 characters**. Characters are counted in a fixed order: 1. every exception `name`, 2. then every exception `message`, 3. then every log `message`. When the budget runs out, the message being counted is cut and gets a marker such as `<<<Logpush: exception messages truncated>>>` or `<<<Logpush: messages truncated>>>`, and later messages are dropped. Because log lines are counted last, a chatty Worker loses its `console` output first, while exception names survive longest. Short, structured log lines keep more of what matters inside the budget. ## Controlling volume Logpush sends every event from every flagged Worker unless the job says otherwise, so a busy Worker can produce a large, costly stream. The levers sit in two places: - **On the job**: a `filter` that keeps only some outcomes or scripts, a **sampling rate** that sends a fraction of events, and `field_names` that leave out fields nobody reads. - **In the Worker**: shorter, structured `console` messages, which also keep more content inside the 16,384-character budget. - **In the flag**: leaving `logpush` off for Workers whose events nobody needs outside Cloudflare. ## How it compares | Path | Where data goes | Kept for | |---|---|---| | Workers Logs | Cloudflare's own store, queried in the dashboard | 3 days Free, 7 days Paid | | Workers Trace Events Logpush | Your destination, per the job | Whatever the destination keeps | | Tail Worker | Wherever your code sends it | Whatever your code does | | OpenTelemetry export | An external OpenTelemetry destination, in batches | Whatever the destination keeps | ## The current recommendation Cloudflare's Logpush page now suggests OpenTelemetry export for new integrations: it carries traces as well as logs, works with any OpenTelemetry-compatible destination, and can be set with `persist: false` so the data is not also stored in Cloudflare. Logpush remains a reasonable path when a team already runs Logpush jobs for other datasets and wants Worker events in the same pipeline.

  • A team adds `logpush: true` to a Cloudflare Worker and deploys, but the destination stays empty. What is missing?
    The account-level Logpush job. The flag only marks the Worker; the job on the `workers_trace_events` dataset decides the destination and fields. Someone with Logpush access, such as an Administrator, a Log Share role or a Logs Edit token, has to create it, and the account must be on Workers Paid.
  • In which order does Workers Trace Events Logpush spend its 16,384-character budget?
    Exception names first, then exception messages, then log messages. Once the budget is gone, the current message gets a truncation marker and the rest are dropped, so `console` output is the first to go. Keep log lines short and structured so the important ones fit.

  • Setting logpush: true in the Wrangler file creates the Logpush job for you.
  • Workers Trace Events Logpush is included on the Workers Free plan.
  • Logpush truncates exception messages before it touches console log messages.
  • Any developer who can deploy the Worker can also create its Logpush job.
  • Logpush exports only uncaught exceptions, never the console.log output.

As of 2026-10-10, Cloudflare's Workers Logpush documentation recommends OpenTelemetry export for new integrations; Workers Trace Events Logpush remains available on Workers Paid.