Documentation Index
Fetch the complete documentation index at: https://mintlify.com/chrisbenincasa/tunarr/llms.txt
Use this file to discover all available pages before exploring further.
Tunarr provides configurable logging to help you monitor server activity and diagnose issues with streaming, media source syncs, and scheduling. Logs can be viewed in the Tunarr web UI, tailed from disk, or streamed in real-time via the API. Logging settings are available under Settings > System > Logging.
Log Levels
Tunarr supports standard log levels ordered from most to least verbose. Setting a level means that level and all levels above it (less verbose) will be captured.
| Level | Description |
|---|
trace | Very detailed trace information — the most verbose output available. |
debug | Detailed information useful for diagnosing specific issues. |
http | Incoming HTTP request logging (numeric value: 25). |
http_out | Outgoing HTTP requests to media servers like Plex and Jellyfin (numeric value: 15). |
info | General operational information. This is the default level. |
warn | Warning conditions that may indicate potential problems. |
error | Error conditions that should be investigated. |
fatal | Critical errors that cause the application to stop. |
silent | No logging output at all. |
For normal day-to-day operation, info is the recommended log level. Use debug or trace only when actively investigating a specific issue, then revert to info to reduce noise and disk usage.
Setting the Log Level
Via the Web UI
Navigate to Settings > System > Logging and select a log level from the dropdown. Changes take effect immediately without a restart.
Via Environment Variable
Set the LOG_LEVEL environment variable to override the UI setting. This is particularly useful in Docker environments where you want to pin the log level at container startup:
For Docker Compose:
environment:
- LOG_LEVEL=debug
Per-Category Log Levels
In addition to the global log level, Tunarr supports setting independent log levels for specific subsystems. This is useful when you want detailed output from one area without flooding logs with output from the entire application.
| Category | Description |
|---|
scheduling | Logs from the channel scheduling and guide generation subsystem. |
streaming | Logs from the streaming and transcode session subsystem. |
info while setting streaming to debug to get detailed stream logs without extra noise from elsewhere.
Per-category log levels are configured in Settings > System > Logging, or via the API:
curl -X PUT "http://localhost:8000/api/system/settings" \
-H "Content-Type: application/json" \
-d '{
"logging": {
"logLevel": "info",
"categoryLogLevel": {
"scheduling": "debug",
"streaming": "trace"
}
}
}'
null or omit it to fall back to the global log level.
Log File Output
By default, Tunarr outputs logs to the console (stdout). To persist logs to disk, enable log file output in Settings > System > Logging and configure a log directory.
Log File Location
Log files are stored in the logs/ subdirectory of your Tunarr data directory:
| Platform | Default Path |
|---|
| Docker | /config/tunarr/logs/ |
| Windows | %APPDATA%\tunarr\logs\ |
| macOS | ~/Library/Preferences/tunarr/logs/ |
| Linux | ~/.local/share/tunarr/logs/ |
LOG_DIRECTORY environment variable:
LOG_DIRECTORY=/path/to/logs
- Main log file:
tunarr.log
- Format: NDJSON (newline-delimited JSON)
Each log entry is a single JSON object on its own line:
{"level":30,"time":1705574400000,"msg":"Server started","hostname":"tunarr","pid":1234}
Log Rotation
Log rotation prevents the tunarr.log file from growing indefinitely by rotating it when it reaches a size threshold.
Configuration Options
| Option | Default | Description |
|---|
| Enabled | false | Enable log file rotation. |
| Max File Size | 1 MB | Rotate when the file exceeds this size. Configurable in bytes via API (e.g., 10485760 for 10 MB). |
| Rolled File Limit | 3 | Number of rotated log files to retain. Older files are deleted when this limit is exceeded. |
| Schedule | (none) | Optional time-based rotation trigger. |
How Rotation Works
When the active log file exceeds the configured size:
tunarr.log is copied to tunarr.log.1- Existing numbered files shift up (
tunarr.log.1 → tunarr.log.2, and so on)
- Files that exceed the rolled file limit are deleted
tunarr.log is truncated and continues receiving new log entries
With a rolledFileLimit of 3, the log directory contains:
tunarr.log (current, active)
tunarr.log.1 (previous rotation)
tunarr.log.2 (older)
tunarr.log.3 (oldest — deleted on next rotation)
Enabling Log Rotation via API
curl -X PUT "http://localhost:8000/api/system/settings" \
-H "Content-Type: application/json" \
-d '{
"logging": {
"logRollConfig": {
"enabled": true,
"maxFileSizeBytes": 10485760,
"rolledFileLimit": 5
}
}
}'
Viewing and Accessing Logs
Via the Web UI
Access logs directly in the Tunarr web interface under Settings > System > Logs.
Via the API
Stream live logs in real-time using Server-Sent Events:
# Raw NDJSON format
curl "http://localhost:8000/api/system/debug/logs/stream"
# Pretty-printed format
curl "http://localhost:8000/api/system/debug/logs/stream?pretty=true"
# Download entire log file
curl "http://localhost:8000/api/system/debug/logs?download=true" -o tunarr.log
# Download last 1000 lines
curl "http://localhost:8000/api/system/debug/logs?download=true&lineLimit=1000" -o tunarr.log
# Download pretty-printed
curl "http://localhost:8000/api/system/debug/logs?download=true&pretty=true" -o tunarr.log
Via the Command Line
# Follow Docker container logs in real-time
docker logs -f tunarr
# Tail the log file directly
tail -f /path/to/tunarr/data/logs/tunarr.log
# Pretty-print JSON logs with jq
tail -f /path/to/tunarr/data/logs/tunarr.log | jq '.'
Troubleshooting with Logs
Recommended Log Levels by Scenario
| Scenario | Recommended Level |
|---|
| Normal operation | info |
| Investigating a streaming issue | debug (set streaming category to debug) |
| Detailed FFmpeg or codec troubleshooting | trace |
| Minimal logging for performance testing | warn or error |
| Silence all logging | silent |
Common Log Patterns
Startup:
Server started on port 8000
Meilisearch started on port 7700
Loading channels...
Syncing Plex library: Movies
Found 500 items in library
Sync completed in 5.2s
FFmpeg process started for channel 1
Stream error: Connection reset by peer
FFmpeg process exited with code 1
Indexing 1000 programs...
Index update completed
Temporarily Increasing Verbosity
To temporarily increase log verbosity for a debugging session without permanently changing your settings, use the LOG_LEVEL environment variable override and restart Tunarr:
Set the log level override
Set LOG_LEVEL=debug in your environment or Docker run command:docker run -e LOG_LEVEL=debug ... chrisbenincasa/tunarr
Reproduce the issue
Perform the action that triggers the problem so the detailed logs are captured.
Collect the logs
Download or tail the log file to capture the relevant output for review or to share when reporting an issue.
Reset the log level
Remove the LOG_LEVEL environment variable and restart Tunarr to return to your normal log level.
debug, trace) generate significantly more output and can have a measurable impact on performance under load. Log rolling adds a small overhead during rotation events. For production deployments, keep the log level at info and only increase verbosity when actively troubleshooting a specific issue.