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
-
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" }] } -
Write the tail() handler
The consumer is a Worker whose
wrangler.jsoncsets"name": "my-tail-worker". It exportstail().export default { async tail(events) { for (const event of events) { console.log(event.outcome, event.event?.request?.url, event.logs); } }, } satisfies ExportedHandler<Env>; -
Run both Workers
Pass one
-cper Worker to oneorange dev. The first one serves the port. See Multiple Workers.orange dev -c wrangler.jsonc -c tail/wrangler.jsonc -
Send a request
Each request to
my-workerreachestail()inmy-tail-workerafter the request ends.curl localhost:8787
How it works
- When an event ends, your Worker appends its
TraceItemto 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 atail()that writes to another system tolerate duplicates. orange devstarts 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 aTraceItemfor eachfetch, service bindingfetch(),scheduled, andqueueevent, 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, andstreaming_tail_consumers. - Migration: Not needed. Cloudflare keeps no tail events to move.
| Feature | Status | Notes |
|---|---|---|
tail() on the default export | Supported | Also tail(events) on a WorkerEntrypoint class. |
fetch, service binding fetch(), scheduled, and queue events | Supported | |
Durable Object events, JS RPC calls, connect(), alarms, and WebSocket events | Not supported | Not traced. |
logs, exceptions, outcome, and errorInfo | Supported | As in workerd. |
| Redacted request headers and URLs | Supported | As in workerd. request.getUnredacted() returns the original values. |
wallTime | Supported | The event’s wall time in milliseconds. |
cpuTime | Not supported | Always 0. |
diagnosticsChannelEvents | Not supported | Always empty. |
| A consumer in another Worker | Supported | In the same orange dev or orange serve. |
streaming_tail_consumers and tailStream() | Not supported | |
Worker Loader tails and streamingTails | Not supported | Accepted. They receive no events. |
Limits
| What | Limit | What happens over it |
|---|---|---|
Failed tail() calls for one batch | 10 | The batch is dropped, and the dev output shows an error. |
| How long an undelivered event waits | 7 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 unreachable | 10,000 per consumer | The oldest are dropped, with an error. |
| One event | 1,000,000 bytes of JSON, less 16 KiB | The event is dropped, with an error. |
| Clock difference between a cluster’s nodes | 60 seconds | An event that a slow node appends to a segment the consumer has left is lost. |
What Orange reads
In wrangler.jsonc | On Orange |
|---|---|
tail_consumers[].service | The Worker itself, or another Worker of the same orange dev or orange serve. |
tail_consumers[].environment | Ignored. |
streaming_tail_consumers | A non-empty list fails the config load with Unsupported Wrangler configuration: streaming_tail_consumers. |
Delivery path
- An event’s
TraceItemis appended when the event ends, after itswaitUntil()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 callstail()with the events of each read. The offset moves only aftertail()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 bindingfetch(),scheduled, andqueueevent of the Worker records itsconsole.debug,console.info,console.log,console.warn, andconsole.errorcalls, 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 withHandler does not export a tail() function., so its batches are retried and then dropped.
Delivery guarantees
| Case | Result |
|---|---|
| Consumer is not running | It gets the events when it starts. |
tail() throws | The 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 saved | The last batch comes again. |
| Overlapping requests | Each TraceItem holds only its own event’s logs and exceptions. |
| A producer stops before its append | Events 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.
| Setting | Default | Meaning |
|---|---|---|
ORANGE_TAIL_SEGMENT_SECONDS | 3600 | Length of one segment |
ORANGE_TAIL_RETENTION_SECONDS | 604800 (7 days) | How long an undelivered segment is kept after it ends |
- Set both in the environment of
orange devororange 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 devstarts one Services process for the session, next to its local Rivet Engine, when a Worker of the session usestail_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_consumersfails to start with an error that says how to install it.RIVET_SERVICES_BINARYpoints 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:
- Deploy the
rivetdev/servicesimage of the same version as@rivet-dev/servicesin Orange’s lockfile, withRIVET_ENDPOINT,RIVET_NAMESPACE, andRIVET_TOKENof the namespace. Its pool name is alwaysservices. - 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.tscompares 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, atail()that throws, a runtime that crashes duringtail(), 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-testanderrorinfo-tail-testfiles run with the Worker as its own tail consumer.