# Backpressure

Logbus pipelines are fully backpressure-aware. A slow downstream stage will automatically slow the upstream stages feeding it — no events are silently dropped and no unbounded memory growth occurs.

## How It Works

Each inter-stage connection is a bounded queue with a fixed capacity. When a stage's input queue is full, the pipeline pauses until space becomes available. This suspension propagates back: sources stop producing, transforms stop processing, and memory usage stays bounded.

```
source ──► [queue] ──► transform ──► [queue] ──► sink
                                         ↑
                              if full, source pauses here
```

### Fan-out & Slow Consumers

When a stage fans out to multiple downstream stages, it delivers to **each** branch before moving on. A slow consumer on one branch will pause delivery to all branches. Design your pipeline topology with this in mind: if one branch can tolerate loss (e.g. a debug tap), route it through a stage that samples or drops events rather than holding up the critical path.

### UI Dashboard Taps

The UI dashboard samples events for display without blocking the pipeline. If the dashboard falls behind, those samples are silently dropped — the pipeline itself is never paused.

## Buffer Size

The default per-channel buffer is **4096 events**. You can change this with `--event-buffer`:

```sh
logbus --event-buffer 1024 pipeline.yml
```

A larger buffer smooths over short bursts; a smaller buffer causes upstream stages to pause sooner, which can reduce latency at the cost of throughput under load.

## Built-in Channels (ERRORS, STATS)

The `ERRORS` and `STATS` virtual channels are also bounded queues of the same capacity. If no stage subscribes to them, those event types are discarded automatically.