Tail Workers

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. Tail Workers can process logs for alerts, debugging, or analytics.

Tail Workers are available to all customers on the Workers Paid and Enterprise tiers. Tail Workers are billed by CPU time, not by the number of requests.

A Tail Worker is automatically invoked after the invocation of a producer Worker (the Worker the Tail Worker will track) that contains the application logic. It captures events after the producer has finished executing. Events throughout the request lifecycle, including potential sub-requests via Service Bindings and Dynamic Dispatch, will be included. You can filter, change the format of the data, and send events to any HTTP endpoint. For quick debugging, Tail Workers can be used to send logs to KV or any database.

Export batches of logs and traces to Sentry, Grafana, Honeycomb and more

If you are using Tail Workers to export logs and errors to observability tools like Sentry, Grafana, Honeycomb and more — you may not need to use Tail Workers.

Instead, you can configure your Worker to export OpenTelemetry (OTEL) format logs and traces to these tools. Unlike Tail Workers, when you configure an OTEL destination, logs and traces are sent in batches to your destination, rather than sent after each invocation of the Worker.

You should think of Tail Workers as the advanced-mode option, for when you need to do something custom that is not built into the Workers observability platform.

Configure Tail Workers

To configure a Tail Worker:

1. Create a Worker to serve as the Tail Worker.
2. Add a tail() handler to your Worker. The tail() handler is invoked every time the producer Worker to which a Tail Worker is connected is invoked. The following Worker code is a Tail Worker that sends its data to an HTTP endpoint:

JavaScript

export default {
  async tail(events) {
    fetch("https://example.com/endpoint", {
      method: "POST",
      body: JSON.stringify(events),
    });
  },
};

The following Worker code is an example of what the events object may look like:

[
  {
    "scriptName": "Example script",
    "outcome": "exception",
    "eventTimestamp": 1587058642005,
    "event": {
      "request": {
        "url": "https://example.com/some/requested/url",
        "method": "GET",
        "headers": {
          "cf-ray": "57d55f210d7b95f3",
          "x-custom-header-name": "my-header-value"
        },
        "cf": {
          "colo": "SJC"
        }
      }
    },
    "logs": [
      {
        "message": ["string passed to console.log()"],
        "level": "log",
        "timestamp": 1587058642005
      }
    ],
    "exceptions": [
      {
        "name": "Error",
        "message": "Threw a sample exception",
        "timestamp": 1587058642005
      }
    ],
    "diagnosticsChannelEvents": [
      {
        "channel": "foo",
        "message": "The diagnostic channel message",
        "timestamp": 1587058642005
      }
    ]
  }
]

3. Add the following to the Wrangler file of the producer Worker:

wrangler.jsonc

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "tail_consumers": [
    {
      "service": "<TAIL_WORKER_NAME>"
    }
  ]
}

wrangler.toml

tail_consumers = [{service = "<TAIL_WORKER_NAME>"}]

Note

Workers added to the tail_consumers array must have a tail() handler defined.

Use Analytics Engine for aggregated metrics

If you need aggregated analytics rather than individual log events, consider writing to Workers Analytics Engine from your Tail Worker. Analytics Engine is optimized for high-cardinality, time-series data that you can query with SQL.

For example, you can use a Tail Worker to count errors by endpoint, track response times by customer, or build usage metrics, then write those aggregates to Analytics Engine for querying and visualization.

JavaScript

export default {
  async tail(events, env) {
    for (const event of events) {
      env.ANALYTICS.writeDataPoint({
        blobs: [event.scriptName, event.outcome],
        doubles: [1],
        indexes: [event.event?.request?.cf?.colo ?? "unknown"],
      });
    }
  },
};

Refer to the Analytics Engine documentation for more details on writing and querying data.

Related resources

• tail() Handler API docs - Learn how to set up a tail() handler in your Worker.
• Analytics Engine - Write custom analytics from your Worker for high-cardinality, time-series queries.
• Errors and exceptions - Review common Workers errors.
• Local development and testing - Develop and test you Workers locally.
• Source maps and stack traces - Learn how to enable source maps and generate stack traces for Workers.