Real-time monitoring for Plex, Jellyfin, and Emby. One dashboard for all your servers.

Tracearr is a monitoring platform for Plex, Jellyfin, and Emby. Track streams in real-time, dig into playback analytics, browse one catalog across every server, and spot account sharing before it gets out of hand.

Screenshots and the feature tour are at tracearr.com, the manual at docs.tracearr.com. Both are updated with every release. This file is the short version.

What It Does

Multi-Server Dashboard - Connect Plex, Jellyfin, and Emby to a single interface. Active streams, server health, and per-server CPU, memory, and bandwidth charts sit on one page. Plex reports its own numbers; Jellyfin and Emby report theirs through the Tracearr SSE plugin.

Session Tracking - Complete session history: who watched what, when, where, and on what device. Every stream includes geolocation data with ASN, continent, and postal code.

Stream Analytics - See what's transcoding vs direct playing, track bandwidth usage, and see what people watch. Codec breakdowns, resolution stats, device compatibility scores.

One Person, Many Accounts - Someone with a Plex login and a Jellyfin login is one identity here. Merge duplicates by hand or take the suggestions, and split them again if you get it wrong. An identity's trust score is the worst of its active accounts, so merging never hides a problem.

Media Catalog - One record per title, matched across servers by IMDb, TMDB, or TVDB id, with each server's copies attached. Six pages sit under Media:

• Overview - Library stat cards, growth over time, recently added and most popular shelves, and a Dead Weight list of never-watched titles.
• Browse - A poster grid over the whole catalog, filtered by type, server, library, genre, resolution, dynamic range, watched state, year, or file size.
• Genres - Plays and watch time by genre, across every server in view.
• Quality - Resolution and codec distribution. Track how your 4K vs 1080p ratio changes.
• Storage - Usage predictions, duplicate detection across servers, stale content, and ROI analysis (watch hours per GB).
• Watch - Engagement metrics, completion rates, viewing patterns by hour and month, binge detection.

Live TV & Music - Track live TV sessions and music playback alongside movies and shows.

Stream Map - Where your streams come from, on a world map you host yourself. The vector basemap ships inside the container, so there are no tile keys and no requests to a third-party tile service. Give a server a location and its local network plays show there too.

Automations - A trigger fires, conditions decide whether it matters, actions run. Eighteen triggers cover sessions, accounts, library changes, server health, update availability, and newsletter results. Actions send a notification, adjust trust, message the client, or stop the stream, and an if action branches on conditions. Twenty-two templates ship built in, among them impossible travel, too many streams at once, simultaneous locations, device velocity, geo restrictions, account inactivity, no 4K transcodes, and stop paused streams. Any automation exports to a share code another instance can paste in.

Trust Scores - Every account starts at 100. Violations lower it, an automation can adjust, set, or reset it, and an identity's score is the lowest of its active accounts.

Destinations - Discord, generic JSON webhook, ntfy, Gotify, Apprise, Pushover, email over SMTP, mobile push, and a toast in the web UI.

Newsletters - Mail your members what was added: movies, shows with their new seasons, albums, and optionally what got watched most. Per server, on a daily, weekly, monthly, or cron schedule, with a window that picks up where the last email stopped. Addresses come from a contact email you set, their Tracearr login, or their Plex account. Every email carries an unsubscribe link and a view-in-browser link, and each send lands in a history tab with per-recipient status and retry.

Public API - Key-authenticated REST API for third-party integrations, v1 and v2. Generate a key under Settings, then read the API reference or the interactive Scalar page at /api-docs on your own instance.

Bulk Actions - Multi-select operations across tables. Acknowledge or dismiss violations in bulk, reset trust scores, delete session history.

Data Import - Bring history with you: Tautulli, a Jellystat backup file, or the Playback Reporting plugin read straight from Jellyfin or Emby.

Why Tracearr?

Tautulli only works with Plex. Jellystat only works with Jellyfin and Emby. If you run multiple servers, you're stuck with multiple dashboards.

Tracearr handles all three. One install, one interface.

Quick Start

# Download compose file
curl -O https://raw.githubusercontent.com/connorgallopo/Tracearr/main/docker/examples/docker-compose.pg18.yml

# Generate secrets
echo "JWT_SECRET=$(openssl rand -hex 32)" > .env
echo "COOKIE_SECRET=$(openssl rand -hex 32)" >> .env

# Deploy
docker compose -f docker-compose.pg18.yml up -d

Open http://localhost:3000 and connect your Plex, Jellyfin, or Emby server.

Unraid users: The supervised image bundles the app, TimescaleDB, and Redis in one container and generates its own secrets on first boot. See docker/examples for details.

For Portainer deployment, alternative configurations, or detailed requirements, see the Docker deployment guide. For full documentation, visit docs.tracearr.com.

Docker Tags

# All-in-one (easiest)
docker pull ghcr.io/connorgallopo/tracearr:supervised

# Stable (requires external services)
docker pull ghcr.io/connorgallopo/tracearr:latest

# Living on the edge
docker pull ghcr.io/connorgallopo/tracearr:nightly

Viewing Logs

Standard Docker - Each service runs in its own container:

docker logs tracearr          # Application logs
docker logs tracearr-postgres # Database logs
docker logs tracearr-redis    # Cache logs

Supervised Docker - All services run in one container. View logs in the web UI at /debug (Log Explorer section), or via CLI:

docker exec tracearr cat /var/log/supervisor/tracearr-error.log

Available log files: tracearr.log, tracearr-error.log, postgres.log, postgres-error.log, redis.log, redis-error.log, supervisord.log

Set LOG_LEVEL=debug for verbose output.

Proxmox VE LXC - Each service runs as a systemd unit:

journalctl -u tracearr   # Application logs
journalctl -u postgresql # Database logs
journalctl -u redis      # Cache logs

Development Setup

# Install dependencies (requires pnpm 12+, Node.js 22.22.2+)
pnpm install

# Start database services
docker compose -f docker/docker-compose.dev.yml up -d
# Includes Mailpit for email testing: SMTP on 1025, inbox at http://localhost:8025

# Copy and configure environment
cp .env.example .env

# Run migrations
pnpm --filter @tracearr/server db:migrate

# Build the stream map basemap (about 550 MB, once)
pnpm basemap

# Start dev servers
pnpm dev

Frontend runs at localhost:5173, API at localhost:3000.

Stack

TimescaleDB handles session history. Regular Postgres works for a few months, but long query histories kill performance. TimescaleDB is built for time-series data, so dashboard stats stay fast: they're pre-computed, not recalculated every page load.

Fastify over Express because it's measurably faster and schema validation catches bad requests before they hit handlers.

MapLibre with a bundled PMTiles basemap replaces the old raster tiles. The archive is a zoom 8 extract of the Protomaps planet build, made at image build time by scripts/fetch-basemap.sh, and ships in the image, so the map works on an instance with no outbound internet access.

SSE for instant sessions - Plex streams session updates in real-time via Server-Sent Events, so streams appear the moment they start. Jellyfin and Emby get the same through the Tracearr SSE plugin; without it they fall back to polling.

Project Structure

tracearr/
├── apps/
│   ├── e2e/          # End-to-end suite
│   ├── server/       # Fastify API, BullMQ workers, Drizzle/TimescaleDB
│   └── web/          # React dashboard
├── packages/
│   ├── emails/       # React Email templates rendered by the server
│   ├── shared/       # Types, Zod schemas, constants
│   ├── test-utils/   # Factories, mocks, custom matchers
│   └── translations/ # i18n strings
├── docker/           # Compose files and images
└── docs/             # Documentation

The Expo app is not in this repo. It lives at Tracearr/Mobile-App and consumes @tracearr/shared and @tracearr/translations as published packages.

Community

Got questions? Found a bug? Want to contribute? Check docs.tracearr.com first, then:

Or open an issue on GitHub.

Contributing

Every change starts as an issue or a Discussion before any code is written. A maintainer labels it planned or help wanted, vouches for your account with !vouch, and only then does a pull request stay open. A PR with no agreed issue behind it is closed regardless of the code, and so is one from an unvouched account. Documentation-only fixes are the one exception to the discussion step.

AI tools are fine to use; you still have to be able to explain and change every line, and significant AI usage goes in the PR template. Submissions from autonomous agents are closed. CONTRIBUTING.md has the full rules, the PR checklist, and the testing commands.

Development with VS Code

Use the included .vscode/launch.json to debug both server and web apps directly from VS Code.

Run pnpm dev in a terminal to start both apps, then use the "Debug All" configuration to attach the debugger.

Roadmap

Shipped

• Multi-server Plex, Jellyfin, and Emby support
• Session tracking with full history
• Automations: triggers, conditions, actions, and 22 built-in templates
• Share codes for exporting and importing an automation
• Nine destination kinds, including email over SMTP and mobile push
• Newsletters with schedules, per-recipient send history, and unsubscribe
• Cross-server identities with merge, split, and worst-account trust
• Media catalog: overview, browse, genres, quality, storage, watch
• Real-time WebSocket updates
• SSE for instant session detection (Plex built-in, Jellyfin/Emby via plugin)
• Live server CPU, memory, and bandwidth charts
• Self-hosted stream map (MapLibre + PMTiles, no tile keys)
• Trust scores
• Tautulli, Jellystat, and Playback Reporting history import
• Transcode analytics & device compatibility
• Live TV & music tracking
• Stream quality metrics (codec, resolution, bitrate)
• Stream termination
• Public REST API v1 and v2 with an interactive Scalar reference
• Bulk actions for violations, users, and sessions
• Enhanced IP geolocation (ASN, continent, postal code)
• Mobile app - iOS and Android

Coming soon

• Tiered access controls

Project Statistics

Star History

License

AGPL-3.0 - Open source with copyleft protection. If you modify Tracearr and offer it as a service, you share your changes.

This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com.

_{For Plex, Jellyfin, and Emby admins who want to see what's actually happening.}

This project is tested with BrowserStack.