Cloudflare Docs
Visit Workers on GitHub
Set theme to dark (⇧+D)


​​ Background

A tail event is the event type to automatically capture data from a producer Worker. It can be used to process logs in real-time and send them to a logging or analytics service.

​​ Synatx: ES modules

For Workers using the ES modules format, handle TailEvent in Workers functions by adding a tail() function to your module’s exported handlers:

export default {
async tail(events, env, ctx) {
fetch("<YOUR_ENDPOINT>", {
method: "POST",
body: JSON.stringify(events),

​​ Parameters

  • events Array

    • An array of TailItems. One TailItem is collected for each event that triggers a Worker. For Workers for Platforms customers with a Tail Worker installed on the Dispatch Worker, events will contain two elements: one for the Dispatch Worker and one for the User Worker.
  • env object

    • An object containing the bindings associated with your Worker using ES modules format, such as KV namespaces and Durable Objects.
  • ctx object

    • An object containing the context associated with your Worker using ES modules format. Currently, this object just contains the waitUntil function.

​​ Synatx: Service Worker

Written using the Service Worker syntax, handle TailEvent in Workers functions by attaching the tail event with addEventListener:

addEventListener('tail', event =>
fetch("<YOUR_ENDPOINT>", {
method: "POST",
body: JSON.stringify(events),

​​ Properties

  • event.type string

    • The type of event. This will always return "tail".
  • event.waitUntil(promisePromise) : void

    • Refer to waitUntil. Note that unlike fetch event handlers, tail handlers do not return a value, so this is the only way for trace Workers to do asynchronous work.

​​ TailItems

​​ Properties

  • scriptName string

    • The name of the producer script.
  • event object

    • Contains information about the Worker’s triggering event.
  • eventTimestamp number

    • Measured in epoch time.
  • logs array

  • exceptions array

    • An array of TailExceptions. A single Worker invocation might result in multiple unhandled exceptions, since a Worker can register multiple asynchronous tasks.
  • outcome string

    • The outcome of the Worker invocation, one of:
      • An uncaught JavaScript exception.
      • A fetch handler that does not result in a Response.
      • An internal error.
      • unknown: outcome status was not set.
      • ok: The worker invocation succeeded.
      • exception: An unhandled exception was thrown. This can happen for many reasons, including:
        • exceededCpu: The Worker invocation exceeded either its CPU limits.
        • exceededMemory: The Worker invocation exceeded memory limits.
        • scriptNotFound: An internal error from difficulty retrieving the script.
        • canceled: The worker invocation was canceled before it completed. Commonly because the client disconnected before a response could be sent.

​​ FetchEventInfo

​​ Properties

​​ TailRequest

​​ Properties

  • cf object

  • headers Object

  • method String

    • The HTTP request method.
  • url String

    • The HTTP request URL (redacted by default).

​​ Methods

  • getUnredacted() Object

    • Returns a TailRequest object with unredacted properties

Some of the properties of TraceRequest are redacted by default to make it harder to accidentally record sensitive information, like user credentials or API tokens. The redactions use heuristic rules, so they are subject to false positives and negatives. Clients can call getUnredacted() to bypass redaction, but they should always be careful about what information is retained, whether using the redaction or not.

  • Header redaction: The header value will be the string “REDACTED” when the (case-insensitive) header name is cookie/set-cookie or contains a substring "auth”, “key”, “secret”, “token”, or "jwt".
  • URL redaction: For each greedily matched substring of ID characters (a-z, A-Z, 0-9, ‘+’, ‘-’, ‘_’) in the URL, if it meets the following criteria for a hex or base-64 ID, the substring will be replaced with the string “REDACTED”.
  • Hex ID: Contains 32 or more hex digits, and contains only hex digits and separators (’+’, ‘-’, ‘_’)
  • Base-64 ID: Contains 21 or more characters, and contains at least two uppercase, two lowercase, and two digits.

​​ TailResponse

​​ Properties

  • status number

    • The HTTP status code.

​​ TailLog

Records information sent to console functions.

​​ Properties

  • timestamp number

    • Measured in epoch time.
  • level String

    • A string indicating the console function that was called. One of: debug, info, log, warn, error.
  • message Object

    • The array of parameters passed to the console function.

​​ TailException

Records an unhandled exception that occurred during the Worker invocation.

​​ Properties

  • timestamp number

    • Measured in epoch time.
  • name String

    • The error type (For example,Error, TypeError, etc.).
  • message Object

    • The error description (For example, "x" is not a function).