> ## 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.

# Disk Sink

> Binary and plaintext file storage with atomic rotation and optional LZ4 compression.

Disk sinks write data to local files. Two types are available: `disk_binary` for high-throughput binary storage and `disk_plaintext` for human-readable logs.

## Plaintext

Human-readable log files, split by data type. Easy to grep, tail, and debug.

```toml theme={null}
[sinks.logs]
type = "disk_plaintext"
path = "/var/log/tell"
rotation = "daily"
compression = "lz4"
```

| Field         | Default   | Notes                                |
| ------------- | --------- | ------------------------------------ |
| `path`        | —         | Output directory (required)          |
| `rotation`    | `"daily"` | `"hourly"` or `"daily"`              |
| `compression` | `"none"`  | `"none"` or `"lz4"` (70-85% smaller) |

### Output format

Events and logs are decoded from FlatBuffer format and written as structured text:

```
[2025-01-15T10:30:45.123Z] [TRACK] device_id=abc123 session_id=xyz789 event_name=button_click source_ip=192.168.1.100 payload={...}
[2025-01-15T10:30:45.123Z] [INFO] session_id=xyz789 source=api service=auth source_ip=192.168.1.100 payload=request completed
```

### Directory structure

Files are separated by type within each workspace and date:

```
logs/
└── workspace_42/
    └── 2025-01-15/
        ├── events.log
        ├── logs.log
        ├── snapshots.log
        └── raw.log        # failed decodes only
```

## Binary

High-performance binary storage with 24-byte metadata headers. Use this for archival when you need maximum throughput and plan to read with `tell read`.

```toml theme={null}
[sinks.archive]
type = "disk_binary"
path = "/data/archive"
rotation = "hourly"
compression = "lz4"
```

| Field         | Default    | Notes                                |
| ------------- | ---------- | ------------------------------------ |
| `path`        | —          | Output directory (required)          |
| `rotation`    | `"hourly"` | `"hourly"` or `"daily"`              |
| `compression` | `"none"`   | `"none"` or `"lz4"` (60-80% smaller) |
| `buffer_size` | 32MB       | Write buffer size                    |

### File format

Each message is stored as:

```
[24-byte metadata][4-byte size][FlatBuffer data]
```

Metadata contains the batch timestamp (8 bytes, Unix ms) and source IP (16 bytes, IPv6 format). Read binary files with `tell read`:

```bash theme={null}
tell read /data/archive/1/2025-01-15/10/data.bin
```

## Atomic rotation

Both disk sinks use atomic rotation for zero data loss during file switches. The hot write path is lock-free and non-blocking. File rotation runs on a separate task and checks every 60 seconds.

If the write queue fills up (sink can't keep up), batches are dropped for that sink and logged as backpressure events.