Tracearr

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](https://tracearr.com), the manual at [docs.tracearr.com](https://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](https://github.com/Tracearr/Media-Server-SSE). **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. **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](https://docs.tracearr.com/api) 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. | | Tautulli | Jellystat | Tracearr | | ------------------------------ | -------- | --------- | -------- | | Watch history | ✅ | ✅ | ✅ | | Statistics & graphs | ✅ | ✅ | ✅ | | Session monitoring | ✅ | ✅ | ✅ | | Transcode analytics | ✅ | ✅ | ✅ | | Live TV & Music | ✅ | ✅ | ✅ | | Account sharing detection | ❌ | ❌ | ✅ | | Impossible travel alerts | ❌ | ❌ | ✅ | | Trust scoring | ❌ | ❌ | ✅ | | Plex support | ✅ | ❌ | ✅ | | Jellyfin support | ❌ | ✅ | ✅ | | Emby support | ❌ | ✅ | ✅ | | Multi-server dashboard | ❌ | ❌ | ✅ | | Cross-server user identities | ❌ | ❌ | ✅ | | Cross-server media catalog | ❌ | ❌ | ✅ | | Cross-server duplicate finding | ❌ | ❌ | ✅ | | IP geolocation | ✅ | ✅ | ✅ | | Library analytics | ✅ | ✅ | ✅ | | Public API | ✅ | ✅ | ✅ | | Newsletters | ✅ | ❌ | ✅ | | Import from Tautulli | - | ❌ | ✅ | | Import from Jellystat | ❌ | - | ✅ | ## Quick Start ```bash # 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](docker/examples/README.md) for details. For Portainer deployment, alternative configurations, or detailed requirements, see the [Docker deployment guide](docker/examples/README.md). For full documentation, visit [docs.tracearr.com](https://docs.tracearr.com). ### Docker Tags | Tag | Description | | -------------------- | -------------------------------------------------- | | `latest` | Stable release (requires external DB/Redis) | | `supervised` | All-in-one stable release | | `next` | Latest prerelease (requires external DB/Redis) | | `supervised-next` | All-in-one prerelease | | `nightly` | Bleeding edge nightly (requires external DB/Redis) | | `supervised-nightly` | All-in-one nightly build | ```bash # 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: ```bash 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: ```bash 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: ```bash journalctl -u tracearr # Application logs journalctl -u postgresql # Database logs journalctl -u redis # Cache logs ``` ### Development Setup ```bash # 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 # Start dev servers pnpm dev ``` Frontend runs at `localhost:5173`, API at `localhost:3000`. ## Stack | Layer | Tech | | ---------- | --------------------------------------------------------- | | Frontend | React 19, TypeScript 7, Vite 8, Tailwind CSS 4, shadcn/ui | | Data layer | TanStack Query, TanStack Table | | Charts | Highcharts 13 | | Maps | MapLibre GL 6 over self-hosted PMTiles | | Backend | Node.js 22, Fastify 5 | | Database | TimescaleDB (PostgreSQL extension), Drizzle ORM | | Jobs | Redis and BullMQ | | Real-time | Socket.io | | Email | React Email, SMTP through Nodemailer | | Monorepo | pnpm 12, Turborepo, oxlint, Vitest | **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 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](https://github.com/Tracearr/Media-Server-SSE); without it they fall back to polling. ## Project Structure ``` tracearr/ ├── apps/ │ ├── e