​

Live tail streaming model

​

1. What the tail is — and is not

• Scoped to one tenant per connection. Every row that crosses the stream was authenticated against your organization; the connection itself sees exactly that one tenant’s traffic. Two tenants’ tails never share rows, a connection cap, or a Redis channel.
• Sub-second from response to frame. A request’s row is published from the response-completed hook and lands on open connections while the next request is still in flight — the bar this surface ships against is sub-second, not the tens of seconds a provider console log typically lags.
• A live view, not a system of record. The stream carries only recent rows plus whatever sends while you are connected. The durable, queryable record of your API traffic is the Request Logs surface — a persisted log corpus with cursor pagination over roughly a year of retained history. Reaching the tail without a reconnect cursor gives you a snapshot for watching now, not an archive.

• All authenticated /api/v1/* requests — REST and SDK calls made by your users and API keys.
• Unauthenticated requests are never published. A row exists only if the request resolved to your tenant, so probing, forged, and expired-credential traffic never reaches you.
• Excluded by design: health, readiness, and metrics probes, the tail endpoint itself, and inbound provider webhook ingress (/api/v1/webhooks/…, /api/v1/integrations/webhooks/…). Those receiver-side requests are operator/provider noise on this surface — provider signature failures and replay would read as “customer traffic errors” and dilute the signals the inbound webhook surfaces own. Webhook live-debugging lives in the inbound webhook debug log.

​

2. Stream shape: connect → optional replay → live

1. A connected handshake frame carrying your organization id and the backfill size the stream is about to paint.
2. A backfill of the most recent ~100 request rows in chronological order, so a fresh console session has immediate context.
3. Live rows — one named log frame per completed request, oldest-to-newest, for the rest of the connection.

• The replay buffer is bounded. It holds only recent stream history, capped at roughly the same ~100-row window the connect backfill paints. A cursor that has fallen out of the buffer behaves like a fresh connect: you get the backfill and the live stream, and anything older is gone from this surface.
• Missed history is not lost — it just isn’t here. The durable answer to “what happened while I was disconnected” is the Request Logs surface, whose persisted corpus the tail deliberately does not try to replicate.

​

3. Entry payload model

​

4. Delivery semantics: buffering, drops, isolation, and limits

• Per-tenant isolation. Each tenant’s traffic publishes to its own channel; a single tail connection subscribes to exactly one channel after authenticating to that tenant. No cross-tenant row is ever emitted, and no other tenant’s bursts, drops, or reconnects affect your stream.
• Connection cap. A tenant may hold at most 10 concurrent tail connections, counted cluster-wide. An 11th attempt gets 429 with TOO_MANY_CONNECTIONS; closed tabs and dead peers release their slot promptly (heartbeat cadence), and even a slot leaked wholesale self-heals within an hour. Keep your own consumers to one or two long-lived connections.
• Slow-consumer drop policy. Each connection’s outbound buffer carries a soft cap (1 MB) and a hard cap (5 MB). Over the soft cap, the server drops the frame, writes a : slow_consumer advisory comment frame, and continues — your client stays connected but missed a row, and the cursor you resume from still finds the row in the replay buffer if it is recent. Over the hard cap, the connection is force-closed (the server logs it; you reconnect with your last cursor). Sustained slow consumption therefore degrades you to an incomplete-but-connected stream before it ever risks the API process.
• Failure posture of the pipeline. Row publishing is fire-and-forget from the response hook — a transient outage of the real-time backing store never slows your API responses down. If the backing store is unavailable when you connect, the connection attempt answers 503 rather than hanging; once connected, a replay or backfill failure degrades to live-rows-only, not an error on the stream. Treat 503 and 429 from a server consumer as back-off-and-retry conditions.

​

5. Which observability surface answers which question

​

6. Worked example: a session with reconnect

curl -N "https://api.orbit.devotel.io/api/v1/logs/tail" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Accept: text/event-stream" \
  -H "Origin: https://orbit.devotel.io"

: heartbeat

id: 0
event: connected
data: {"type":"connected","data":{"organizationId":"org_9f2b…","backfill_count":100}}

id: 1812345678901-0
event: log
data: {"type":"log","ts":1758123456789,"request_id":"req_7f3c2a","method":"POST","path_pattern":"/api/v1/messages","status_code":202,"duration_ms":41,"user_id":null,"api_key_id":"key_ab12","error_code":null,"error_message":null,"user_agent":"MyApp/1.4"}

curl -N "https://api.orbit.devotel.io/api/v1/logs/tail" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Accept: text/event-stream" \
  -H "Origin: https://orbit.devotel.io" \
  -H "Last-Event-ID: 1812345678901-0"

​

Related reading

• Tail API reference — endpoint contract, frame schema, SDK and curl consumption, limits and errors.
• Request Logs model — the persisted request-log surface the tail complements.
• Request Logs console guide — the dashboard page, including the Live tail toggle.
• Inbound webhook debug log — the inbound-side surface the tail deliberately excludes.
• Observability stats surface and operator observability map — where aggregates and the wider surface set fit.