Skip to content
Runtime APIs / Tail Workers

Runtime APIs

Tail Workers

Send a Worker's logs, exceptions, and outcomes to the tail() handler of each Worker in its tail_consumers, through Rivet Durable Streams.

A Tail Worker gets the logs, exceptions, and outcome of each event in another Worker, in its tail() handler. You list it in the traced Worker’s tail_consumers, and Orange delivers the events through Rivet Durable Streams.

Quickstart

  1. List the consumer

    In the Worker you want to trace, name the consumer Worker in tail_consumers.

    {
      "name": "my-worker",
      "main": "src/index.ts",
      "compatibility_date": "2026-09-03",
      "tail_consumers": [{ "service": "my-tail-worker" }]
    }
  2. Write the tail() handler

    The consumer is a Worker whose wrangler.jsonc sets "name": "my-tail-worker". It exports tail().

    export default {
      async tail(events) {
        for (const event of events) {
          console.log(event.outcome, event.event?.request?.url, event.logs);
        }
      },
    } satisfies ExportedHandler<Env>;
  3. Run both Workers

    Pass one -c per Worker to one orange dev. The first one serves the port. See Multiple Workers.

    orange dev -c wrangler.jsonc -c tail/wrangler.jsonc
  4. Send a request

    Each request to my-worker reaches tail() in my-tail-worker after the request ends.

    curl localhost:8787

How it works

  • When an event ends, your Worker appends its TraceItem to a Rivet Durable Streams stream for each consumer, after the response.
  • The consumer reads the stream and calls tail() with a batch of events. Delivery is at least once, so make a tail() that writes to another system tolerate duplicates.
  • orange dev starts Durable Streams for you. On a cluster, you deploy Rivet Services yourself.
AI context Compatibility, limits and details

Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.

Compatibility

Status: Partial. Events travel through Rivet Durable Streams.

  • Works: tail() gets a TraceItem for each fetch, service binding fetch(), scheduled, and queue event, with its logs, exceptions, and outcome as in workerd.
  • Differs: Events wait for a consumer that is not running, for up to 7 days. Cloudflare drops them.
  • Missing: Traces of Durable Object, JS RPC, connect(), alarm, and WebSocket events, and streaming_tail_consumers.
  • Migration: Not needed. Cloudflare keeps no tail events to move.
FeatureStatusNotes
tail() on the default exportSupportedAlso tail(events) on a WorkerEntrypoint class.
fetch, service binding fetch(), scheduled, and queue eventsSupported
Durable Object events, JS RPC calls, connect(), alarms, and WebSocket eventsNot supportedNot traced.
logs, exceptions, outcome, and errorInfoSupportedAs in workerd.
Redacted request headers and URLsSupportedAs in workerd. request.getUnredacted() returns the original values.
wallTimeSupportedThe event’s wall time in milliseconds.
cpuTimeNot supportedAlways 0.
diagnosticsChannelEventsNot supportedAlways empty.
A consumer in another WorkerSupportedIn the same orange dev or orange serve.
streaming_tail_consumers and tailStream()Not supported
Worker Loader tails and streamingTailsNot supportedAccepted. They receive no events.

Limits

WhatLimitWhat happens over it
Failed tail() calls for one batch10The batch is dropped, and the dev output shows an error.
How long an undelivered event waits7 days after its segment ends. Set ORANGE_TAIL_RETENTION_SECONDS to change it.The segment expires with its events.
Events a Worker holds while Durable Streams is unreachable10,000 per consumerThe oldest are dropped, with an error.
One event1,000,000 bytes of JSON, less 16 KiBThe event is dropped, with an error.
Clock difference between a cluster’s nodes60 secondsAn event that a slow node appends to a segment the consumer has left is lost.

What Orange reads

In wrangler.jsoncOn Orange
tail_consumers[].serviceThe Worker itself, or another Worker of the same orange dev or orange serve.
tail_consumers[].environmentIgnored.
streaming_tail_consumersA non-empty list fails the config load with Unsupported Wrangler configuration: streaming_tail_consumers.

Delivery path

  • An event’s TraceItem is appended when the event ends, after its waitUntil() tasks. The append runs after the response, so the request does no I/O for it.
  • In the consumer Worker, one internal actor per consumer, openorange:tail, reads the stream from its saved offset and calls tail() with the events of each read. The offset moves only after tail() returns.
  • When tail() throws, the same events come again after a pause that doubles from 1 second up to 60 seconds.

Traced events

  • Each fetch, service binding fetch(), scheduled, and queue event of the Worker records its console.debug, console.info, console.log, console.warn, and console.error calls, the errors that its handler throws, and its outcome.
  • The record goes to the stream of each consumer’s current segment, tail/<consumer>/<n>.
  • Log messages and exception fields follow workerd’s format.
  • A tail() invocation is not traced, so a Worker can tail itself.
  • A consumer without a tail() handler fails each call with Handler does not export a tail() function., so its batches are retried and then dropped.

Delivery guarantees

CaseResult
Consumer is not runningIt gets the events when it starts.
tail() throwsThe same events come again.
The runtime crashes during tail()The same events come again after a restart.
The runtime crashes after tail() returns, before the offset is savedThe last batch comes again.
Overlapping requestsEach TraceItem holds only its own event’s logs and exceptions.
A producer stops before its appendEvents not yet appended, at most a few milliseconds’ worth, are lost.

After 10 failed calls, the dev output shows Dropped <n> tail event(s) for <consumer> after 10 failed tail() calls.

Segments and retention

Each consumer’s events go to one stream per time window, a segment. The consumer deletes a segment once it has read past it. A segment that no consumer reads expires on its own after the retention.

SettingDefaultMeaning
ORANGE_TAIL_SEGMENT_SECONDS3600Length of one segment
ORANGE_TAIL_RETENTION_SECONDS604800 (7 days)How long an undelivered segment is kept after it ends
  • Set both in the environment of orange dev or orange serve, not in a Worker’s vars, so every Worker of the deployment uses the same values.
  • Orange keeps at most 2,048 segments in the retention, and makes segments longer to stay under it.
  • The consumer reads a segment it has left once more, up to 60 seconds after the segment ends (or one segment length, if shorter), for appends that land late. That is why a cluster’s clocks must agree to within 60 seconds.

Errors a producer reports

  • Tail events for <consumer> wait: Durable Streams is unreachable. Tail Workers need Rivet Services in the envoy pool `services`; orange dev starts it, and a cluster needs its own Services deployment. The first failed append of an outage prints it once. The Worker retries the append with a pause that doubles from 100 ms up to 10 seconds.
  • Dropped <n> tail event(s) for <consumer>: the append buffer is full, when more than 10,000 events wait.
  • Dropped a tail event of <size> bytes for <consumer>: it exceeds the append limit, for an event over the Durable Streams append limit of 1,000,000 bytes, less 16 KiB.

Rivet Services

Durable Streams runs in Rivet Services, which Orange installs with RivetKit as @rivet-dev/services.

  • orange dev starts one Services process for the session, next to its local Rivet Engine, when a Worker of the session uses tail_consumers. The session’s first Worker starts it. It stops with the session, also when the runtime crashes.
  • Its log is in .open-orange/rivetkit/<id>/.rivetkit/var/logs/rivet-services/.
  • Orange calls the streams through the Engine, so the Services HTTP port is not used. Services binds a free port on 127.0.0.1.
  • Without the Services binary, a Worker with tail_consumers fails to start with an error that says how to install it. RIVET_SERVICES_BINARY points to another binary.

On a cluster

orange serve does not start Services. The cluster’s Rivet namespace needs a Services deployment in the envoy pool services, next to the Orange pool:

  1. Deploy the rivetdev/services image of the same version as @rivet-dev/services in Orange’s lockfile, with RIVET_ENDPOINT, RIVET_NAMESPACE, and RIVET_TOKEN of the namespace. Its pool name is always services.
  2. Orange’s token needs to create and call actors in that namespace.

Until Services runs, the producers keep events in memory, up to 10,000 per consumer. The first failed append prints the error that names the missing services pool.

Conformance

  • tests/events/tail-consumers.test.ts compares a Worker that tails itself and another Worker with workerd 1.20260903.1, including a handler that throws and 20 overlapping requests. It also covers a consumer that was not running, a tail() that throws, a runtime that crashes during tail(), a missing Services binary, the deletion of a delivered segment, the expiry of an undelivered one, and Services after its runtime is killed.
  • The upstream self-logger-test and errorinfo-tail-test files run with the Worker as its own tail consumer.