Source: https://cliparr.dev/docs/logging/

Documentation

# Logging

Choose server log formats, levels, file rotation, and safe sharing defaults.

Development server logs are emitted as JSON Lines so every local console line includes Cliparr’s structured LogTape fields. Frontend development logs use the same JSON format in the browser console.

Production server logs default to `pretty`, the readable terminal format that shows the timestamp, level, category, and message. Set `CLIPARR_LOG_FORMAT=json` or `CLIPARR_LOG_FORMAT=logfmt` in production when you want each console line to include structured fields such as `event.name`, `event.outcome`, request data, provider IDs, media handle IDs, counts, durations, and error details. JSON is best for log collectors. logfmt is compact and readable in plain terminals.

Structured console logs

macOS / Linux

```bash
docker run -d \
  --name cliparr \
  -p 7171:7171 \
  -e APP_KEY="your-32-char-stable-random-secret" \
  -e CLIPARR_LOG_FORMAT=json \
  -v cliparr-data:/data \
  ghcr.io/techsquidtv/cliparr:latest
```

PowerShell

```powershell
docker run -d `
  --name cliparr `
  -p 7171:7171 `
  -e APP_KEY="your-32-char-stable-random-secret" `
  -e CLIPARR_LOG_FORMAT=json `
  -v cliparr-data:/data `
  ghcr.io/techsquidtv/cliparr:latest
```

`CLIPARR_LOG_LEVEL` controls how much the server emits. Development defaults to `debug`; production defaults to `info`. Use `trace` only while chasing detailed media proxy or playback behavior because it can be noisy.

## File logging

Set `CLIPARR_LOG_FILE` to write a second server log destination in addition to the console. File logging is opt-in and rotates by size so diagnostics do not grow forever on long-running installs.

Rotating file logs

```yaml
services:
  cliparr:
    image: ghcr.io/techsquidtv/cliparr:latest
    environment:
      - APP_KEY=replace-this-with-a-32-character-secure-random-string
      - CLIPARR_LOG_FORMAT=pretty
      - CLIPARR_LOG_FILE=/data/logs/cliparr.log
      - CLIPARR_LOG_FILE_FORMAT=json
      - CLIPARR_LOG_FILE_MAX_SIZE=10mb
      - CLIPARR_LOG_FILE_MAX_FILES=5
    volumes:
      - cliparr-data:/data
```

Relative file paths resolve from the server working directory. In containers, prefer a path under `/data` so logs persist with the Cliparr volume. File logs default to JSON unless `CLIPARR_LOG_FILE_FORMAT` is set. If `CLIPARR_LOG_FILE_FORMAT` is omitted but `CLIPARR_LOG_FORMAT` is set, the file uses that configured production log format.

`CLIPARR_LOG_FILE_MAX_SIZE` accepts byte sizes with optional `b`, `kb`, `mb`, `gb`, `kib`, `mib`, or `gib` suffixes and defaults to `10mb`. `CLIPARR_LOG_FILE_MAX_FILES` defaults to `5` and includes the active file, so the default keeps `cliparr.log` plus up to four rotated files.

Sharing logs

Cliparr avoids logging tokens, credentials, raw auth URLs, subtitle text, and full media metadata by default. Logs can still include source IDs, media handle IDs, request paths, durations, status codes, and sanitized upstream paths, so review them before posting publicly.