> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tell.rs/llms.txt
> Use this file to discover all available pages before exploring further.

# Live Tail

> Stream data in real time with filters, sampling, and regex match.

Stream events, logs, and syslog messages as they flow through Tell's pipeline. The tail connects to a running Tell server via Unix socket and decodes batches in real time — useful for debugging, monitoring deploys, and verifying that data is flowing correctly.

```bash theme={null}
tell tail
```

This streams everything. In production, you'll want filters.

## Filtering

**Server-side filters** are applied before data leaves the server — use these to reduce volume:

```bash theme={null}
# Only events from workspace 1
tell tail --workspace 1

# Only error logs from the HTTP source
tell tail --type log --level error --source http

# 1% sample at max 100 batches/sec
tell tail --sample 0.01 --rate-limit 100
```

**Client-side filters** match content after decoding:

```bash theme={null}
# Events matching a glob pattern
tell tail --event "purchase_*"

# Regex match across any string field
tell tail --match "timeout|connection refused"

# Combine: error logs mentioning payments
tell tail --type log --level error --match "payment"
```

All filter flags are repeatable — `--workspace 1 --workspace 2` streams from both.

## Output formats

```bash theme={null}
tell tail                          # colored text (default)
tell tail --output json            # one JSON object per event
tell tail --output compact         # single-line summary per event
tell tail --output raw             # raw decoded FlatBuffer data
tell tail --metadata-only          # batch metadata without payload decode
```

Use `--output json` for piping into `jq` or other tools:

```bash theme={null}
tell tail --type event --output json | jq '.event_name'
```

## Replay

Replay the last N batches from the server's ring buffer on connect:

```bash theme={null}
tell tail --last 50
```

This is useful for catching up on what just happened without waiting for new data.

## Setup

The tail connects to Tell's tap server via Unix socket. The tap server starts automatically with `tell run` — no extra configuration needed. The default socket path is derived from your data directory.

To connect to a specific socket:

```bash theme={null}
tell tail --socket /tmp/tell-tap.sock
```

<Note>
  `tell tail` is available on Unix systems only (macOS, Linux). It requires the `tail` feature flag at build time, which is included in the default build.
</Note>

## What's next

* [CLI commands](/tools/commands#tell-tail) — full flag reference for `tell tail`
* [Pipeline overview](/pipeline/overview) — understand what flows through the pipeline
* [Sources overview](/pipeline/sources/overview) — where the data you're tailing comes from