Tracearr Setup Guide for Plex, Jellyfin, and Emby Monitoring
Rights, lawful use, and scope: This guide is for private monitoring and administration of media servers that host media you own or are authorized to use. It is not legal advice and it is not a guide to acquiring, sharing, or processing copyrighted works without permission.
Quick Answer
Deploy Tracearr with its current Docker Compose stack: Tracearr, TimescaleDB, and Redis. Keep the dashboard private, use unique authentication secrets, connect disposable Plex, Jellyfin, or Emby endpoints first, and prove one Direct Play event, one transcode, one alert-only rule, restart persistence, and backup restore. On August 24, 2026, v2.1.0 is stable and v2.2.0-beta.3 is prerelease. A healthy container alone proves none of those workflows.
Privacy warning: Tracearr-style analytics can expose usernames, IP addresses, locations, devices, watch history, timestamps, and household behavior. Treat the dashboard, logs, exports, screenshots, and backups as private data.
Evidence status: Current Tracearr documentation, the official repository, and release records were checked on August 24, 2026. TechGeeks did not deploy Tracearr, migrate a v1 database, connect a media server, ingest a stream, import history, fire an alert, capture a screenshot, or restore a backup. Every command, output, and success state below is an unperformed example or planned acceptance test.
Tracearr is the observability layer for a media homelab. Plex, Jellyfin, and Emby serve media; Tracearr turns their playback activity into live sessions, history, library views, rules, and operator evidence. It does not replace media-server logs, host metrics, or human review.
Current-version boundary: Tracearr v2.0.0 introduced a heavy database migration, and v2.1.0 is the current stable release. Its release notes require Media-Server-SSE 0.4.0 or newer for Jellyfin and Emby CPU/RAM charts. The v2.2 line is prerelease and is not this production baseline. Back up before every upgrade and restore the matched old database before starting old code.
Where Tracearr Fits
Tracearr sits after playback begins. It does not replace Plex, Jellyfin, Emby, Sonarr, Radarr, Prowlarr, SABnzbd, or Tdarr. It watches media server sessions and turns them into live status, history, playback analytics, rules, alerts, and operator evidence.
Click each step to see how Tracearr turns media server activity into useful operational evidence.
Tracearr vs Tautulli vs General Monitoring
| Question | Tautulli Style | Tracearr Style | General Monitoring |
|---|---|---|---|
| Who is watching Plex? | Strong Plex watch history and notifications. | Also watches Plex and can include Jellyfin/Emby in one dashboard. | Usually does not understand media sessions. |
| Can I see direct play vs transcode? | Yes for Plex. | Yes as playback analytics across supported media servers. | Only indirectly through CPU/GPU metrics. |
| Can I import old history? | It is the old history source for Plex. | Can import from Tautulli or Jellystat depending on server type and support. | No media history import. |
| Can I detect account-sharing patterns? | Limited or custom. | Rules can flag concurrent streams, impossible travel, geo restrictions, and other patterns. | Not media-user aware. |
| Can I tune Tdarr/Plex from it? | Some signal from Plex behavior. | Good signal for direct-play ratio, transcode hotspots, devices, bandwidth, and user patterns. | Good host signal, but not user/session context. |
Who This Is For
- A Plex, Jellyfin, or Emby operator who wants one playback-monitoring dashboard.
- A homelab owner replacing or supplementing Tautulli, Jellystat, or Playback Reporting while preserving the old system until validation passes.
- Someone diagnosing Direct Play, transcode, client, subtitle, bandwidth, or resource patterns from playback evidence.
- An operator who wants the current supported Docker topology and a recoverable update path.
- A privacy-conscious admin who will protect watch history and user data.
Before You Start: Safe Defaults
| Decision | Recommended Starting Point | Why It Matters |
|---|---|---|
| Access | LAN or VPN only | Tracearr contains private session and account behavior. |
| Rules | Alert-only first | Do not terminate streams or punish users until signals are validated. |
| Claim code | Use a temporary random claim code | Initial setup should not be open to anyone who reaches the port. |
| Database | PostgreSQL with TimescaleDB | Tracearr stores time-series session data. |
| Redis | Local Redis service | Tracearr uses Redis for cache and background job queues. |
| Backups | Use database dumps or Tracearr backup features | Do not copy live raw PostgreSQL files as a backup. |
| Logs | Info level unless debugging | Debug logs may contain private operational details. |
Terms You Need
| Term | Plain-English Meaning | Why It Matters |
|---|---|---|
| Session | One active playback stream. | The basic unit Tracearr observes. |
| Direct play | The client plays the file without server-side conversion. | Usually easier on server CPU/GPU. |
| Remux / Direct Stream | Product-specific labels for repackaging streams; Jellyfin reports container-only work as Remux, while Plex Direct Stream may also report a partial audio conversion. | Do not equate labels across products. Record the server, per-stream video/audio state, and matching log. |
| Transcode | The server converts video or audio for the client. | Cost depends on which streams and pipeline stages changed; audio-only conversion is not a video transcode. |
| Bandwidth | Network throughput used by streams. | Helps spot remote pressure and ISP bottlenecks. |
| Geolocation | Approximate location inferred from IP data. | Useful context, but not perfect evidence. |
| Trust score | A risk signal based on defined behavior. | Should guide review, not replace judgment. |
| Impossible travel | A user appears in far-apart places too quickly. | Can indicate sharing, VPN use, mobile networks, or geolocation error. |
| Concurrent stream | Multiple streams by one user at the same time. | May be normal in a household or suspicious depending on your policy. |
| Redis | Fast cache and queue service. | Tracearr needs it for background work. |
| TimescaleDB | PostgreSQL extension for time-series data. | Tracearr uses it for session and analytics history. |
Install the Current Docker Compose Stack
The current official quick start downloads docker/examples/docker-compose.pg18.yml and starts Tracearr, TimescaleDB, and Redis. The compose file itself labels PostgreSQL 18 experimental and new-install-only, so do not point it at an older PostgreSQL volume. Existing deployments need the documented upgrade path and their current database topology, not this fresh-install procedure.
Example commands for a new isolated install (not performed):
install -d -m 0750 "$HOME/tracearr"
cd "$HOME/tracearr"
curl -fLO https://raw.githubusercontent.com/connorgallopo/Tracearr/v2.1.0/docker/examples/docker-compose.pg18.yml
sha256sum docker-compose.pg18.yml
umask 077
printf 'JWT_SECRET=%s\n' "$(openssl rand -hex 32)" > .env
printf 'COOKIE_SECRET=%s\n' "$(openssl rand -hex 32)" >> .env
printf 'BETTER_AUTH_SECRET=%s\n' "$(openssl rand -hex 32)" >> .env
printf 'ENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" >> .env
printf 'CLAIM_CODE=%s\n' "$(openssl rand -hex 24)" >> .env
printf 'DB_PASSWORD=%s\n' "$(openssl rand -hex 32)" >> .env
printf 'PORT=127.0.0.1:3000\n' >> .env
printf 'CORS_ORIGIN=http://127.0.0.1:3000\n' >> .env
printf 'TRUST_PROXY=false\n' >> .env
printf 'TZ=Etc/UTC\n' >> .env
chmod 0600 .env
Example expected output (not observed):
<SHA256> docker-compose.pg18.yml
Review the tag-pinned file before use and retain its recorded hash. The PORT value makes the official short port mapping resolve to loopback-only; replace loopback with one trusted management address only when the access path requires it. Keep every generated value private and preserve the same JWT_SECRET and ENCRYPTION_KEY with backups: changing them can invalidate sessions or make encrypted notification credentials unrecoverable. Treat CLAIM_CODE as temporary bootstrap material.
Example stable-image override (not performed):
services:
tracearr:
image: ghcr.io/connorgallopo/tracearr:v2.1.0
environment:
BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
ENCRYPTION_KEY: ${ENCRYPTION_KEY}
CLAIM_CODE: ${CLAIM_CODE}
CORS_ORIGIN: ${CORS_ORIGIN}
TRUST_PROXY: ${TRUST_PROXY}
Save that as compose.override.yaml. For a reverse proxy, set one exact HTTPS origin, preserve Host, forward X-Forwarded-Host and X-Forwarded-Proto, and set TRUST_PROXY=true only for a trusted proxy path. Do not leave CORS_ORIGIN=* on a production login surface.
Example start and inspection commands (not performed):
docker compose -f docker-compose.pg18.yml -f compose.override.yaml config --quiet
docker compose -f docker-compose.pg18.yml -f compose.override.yaml pull
docker compose -f docker-compose.pg18.yml -f compose.override.yaml up -d
docker compose -f docker-compose.pg18.yml -f compose.override.yaml ps
docker port tracearr 3000/tcp
docker image inspect ghcr.io/connorgallopo/tracearr:v2.1.0 \
--format '{{index .RepoDigests 0}}'
curl -fsS http://127.0.0.1:3000/health
Example expected output (not observed):
tracearr Up ...
tracearr-db Up ... (healthy)
tracearr-redis Up ... (healthy)
127.0.0.1:3000
ghcr.io/connorgallopo/tracearr@sha256:<ARCHITECTURE_SPECIFIC_DIGEST>
<HEALTH_RESPONSE_FOR_THE_SELECTED_RELEASE>
Record the actual digest and actual health response. Do not publish placeholders as results. Process health does not prove authentication, server ingestion, history, alerts, plugins, or restore.
Source Installation Boundary
Tracearr's current production quick start is Docker Compose. Upstream source instructions are development-oriented, and the archived v1.5 source/systemd recipe previously carried here does not match the v2.1 application, package, migration, and PostgreSQL topology. It has been removed so readers are not given an unvalidated production path or broad host/database mutations.
Contributors should work from a disposable environment and the exact release tag, then follow that tag's package metadata, development Compose files, build scripts, and migration notes. No native v2.1 service procedure or native-install output was validated for this revision.
First-Run Validation
- Open Tracearr through LAN, VPN, localhost tunnel, or a hardened reverse proxy.
- Create the first local owner account and record the recovery path privately.
- Connect one disposable Plex, Jellyfin, or Emby endpoint with synthetic users and libraries.
- Confirm the server connection without enabling automated stream termination.
- Start known Direct Play, container-only remux, audio-conversion, and video-transcode workloads using authorized test media where the selected server/client supports them.
- For each session, record Tracearr's label plus the media server's per-stream video/audio method, user, client, server, bandwidth, and UTC interval.
- Confirm the sessions appear in history and corroborate them with the media-server dashboard and matching logs; Tracearr is a secondary observer, not proof of the conversion pipeline by itself.
- Restart Tracearr and its host, then confirm authentication, server connection, and history persist.
Connect Plex, Jellyfin, and Emby Deliberately
| Server | First proof | Current v2.1 boundary |
|---|---|---|
| Plex | Direct Play plus a controlled Direct Stream or transcode appear with matching user, client, timestamps, and per-stream conversion detail. | Plex Direct Stream can be container-only or partially transcoded with video copied and audio converted. Keep the Plex token private and verify the event against Plex's dashboard or logs. |
| Jellyfin | Direct Play plus a controlled Remux, Direct Stream, or Transcode appears with matching synthetic user, client, and per-stream detail. | Jellyfin distinguishes Remux, Direct Stream, and Transcode. Media-Server-SSE 0.4.0 or newer is required for v2.1 CPU/RAM charts; plugin presence does not prove ingestion. |
| Emby | Direct Play plus a controlled conversion appears with matching synthetic user, client, timestamps, and per-stream detail. | Media-Server-SSE 0.4.0 or newer is required for v2.1 CPU/RAM charts. Verify plugin and server versions together. |
Connect only servers the operator is authorized to administer. Use private service URLs where possible. The monitoring account should have only the access the supported integration needs; do not reuse a daily owner credential in public examples or screenshots. A test button or successful connection is not session-ingestion proof.
Import Existing History Carefully
If you are replacing Tautulli, Jellystat, or a Playback Reporting workflow, keep the old system available until import and validation are complete. Tracearr v2.1 documents Jellyfin and Emby imports from the Playback Reporting plugin over the configured server connection; the operator chooses the server timezone because the source timestamps are server-local. A repeat import is intended to skip already imported rows, but that behavior still requires evidence in your environment.
- Back up the source history system and Tracearr first.
- Record source, plugin, media-server, timezone, and Tracearr versions.
- Connect the matching media server before importing.
- Use the current check or preview step to confirm the plugin and source record count.
- Import a bounded date range first.
- Compare users, earliest/latest timestamps, recent sessions, duplicate skips, and unmatched rows.
- Run the same bounded import again only as a safe duplicate test and preserve the real result.
- Keep the source system stopped-but-restorable until notifications, reports, and routine operations are replaced.
Example Tautulli discovery and backup commands (not performed; paths vary by installation):
sudo systemctl status snap.tautulli.tautulli.service --no-pager || true
sudo systemctl cat snap.tautulli.tautulli.service || true
sudo install -d -m 0750 /opt/app-backups/tautulli-pre-tracearr
sudo tar -C / -czf \
/opt/app-backups/tautulli-pre-tracearr/tautulli-data.tgz \
root/snap/tautulli/common/Tautulli 2>/dev/null || true
Example expected result (not observed): the real service definition is recorded and the archive is created only if that Snap path exists. Inspect and restore-test the archive before treating it as a migration exit.
Rules: Start Alert-Only
Tracearr rules are powerful because they can evaluate session behavior and take action. The correct first posture is alert-only. Notify the admin, review the evidence, and only later decide whether any rule should terminate streams or message users automatically.
| Rule Area | Good First Use | Risk to Avoid |
|---|---|---|
| Concurrent streams | Notify when a user exceeds your expected stream count. | Terminating normal household usage before policy is clear. |
| Impossible travel | Flag sessions that appear geographically impossible. | Assuming geolocation is perfect or ignoring VPN/mobile network behavior. |
| Geo restrictions | Notify on unexpected countries or regions. | Blocking travel, VPN, or inaccurate IP data too aggressively. |
| Heavy transcoding | Notify when a user or client repeatedly transcodes large streams. | Punishing users for a client setting you can help them fix. |
| Inactive accounts | Review dormant users before pruning access. | Deleting access without a retention and communication policy. |
Rules should move from observation to decision only after you trust the signal.
Use Tracearr to Diagnose Playback
Tracearr becomes useful when its session record is compared with the Plex, Jellyfin, or Emby dashboard and the media server's own playback or transcoder log. If one client transcodes everything, the cause may be codec support, subtitles, audio, bitrate policy, or network limits rather than a missing GPU. Use the Direct Play vs transcoding owner for the playback-method decision and the media-stack monitoring owner for broader dashboard and log correlation.
| Tracearr Signal | Possible Meaning | Operational Response |
|---|---|---|
| High transcode ratio | A client, file, subtitle, audio, network, or quality-policy mismatch may be common. | Sample matching media-server sessions and logs before changing clients, files, or Tdarr policy. |
| Many remote high-bitrate streams | Remote bandwidth demand may be approaching measured path capacity. | Compare session peaks with measured upload and client limits before changing quality policy. |
| One user transcodes everything | The user's client, selected tracks, quality setting, route, or file mix may differ. | Compare controlled sessions and change one variable at a time; do not attribute cause from the aggregate alone. |
| Peak playback overlaps Tdarr jobs | Batch work may compete with user playback. | Correlate CPU/GPU/storage evidence, then lower Tdarr workers during viewing hours if competition is proven. |
| Low engagement with a library | Content may be stale, seasonal, newly added, or mismatched with household use. | Review retention and request policy with authorized users; analytics alone do not justify deletion. |
| Suspicious multi-location sessions | Possible sharing, VPN, travel, mobile routing, or bad geolocation. | Review before action; do not assume guilt from one signal. |
Backups
Tracearr data is database-backed and privacy-sensitive. Current documentation provides a built-in backup that creates consistent pg_dump snapshots and attempts rollback during restore, but it labels Backup & Restore beta. Do not copy live PostgreSQL or TimescaleDB volume files. Preserve the backup archive, Compose files, image digest, .env, and every secret required to decrypt or authenticate restored data, then prove restore in isolation.
Example backup commands (not performed):
cd "$HOME/tracearr"
docker exec tracearr node apps/server/scripts/backup.ts
install -d -m 0700 "$HOME/tracearr-export"
docker cp tracearr:/data/backup "$HOME/tracearr-export/"
chmod -R go-rwx "$HOME/tracearr-export"
sha256sum "$HOME"/tracearr-export/backup/*
Example expected output (not observed):
<SHA256> /home/<USER>/tracearr-export/backup/<BACKUP_ARCHIVE>
The checksum identifies the copied artifact; it does not prove restore. Store the archive and secrets off-host with restricted access. A restored notification destination may depend on the same encryption material, so secret rotation and restore sequencing must be planned together.
Upgrade Routine
- Read every release note between the installed and target versions and check database, plugin, auth, reverse-proxy, and secret changes.
- Create and export a built-in backup; record its checksum, current Compose hashes, image digest, TimescaleDB image, Redis image, and secrets inventory.
- For the v1-to-v2 boundary, retain the v1.5 backup because v2.0 performs a heavy database migration.
- Pull only the reviewed stable target, not
next,nightly, or a prerelease. - Recreate the app and watch migration progress without interrupting it.
- Verify owner login, user ownership, server connections, Direct Play, transcode, history, import counts, alert-only rules, backups, proxy headers, and restart persistence.
- For Jellyfin or Emby v2.1 live CPU/RAM charts, verify Media-Server-SSE 0.4.0 or newer.
Example update commands (not performed):
cd "$HOME/tracearr"
docker compose -f docker-compose.pg18.yml -f compose.override.yaml pull tracearr
docker compose -f docker-compose.pg18.yml -f compose.override.yaml up -d tracearr
docker compose -f docker-compose.pg18.yml -f compose.override.yaml ps
docker logs --tail=200 tracearr
Example expected result (not observed): the selected stable version starts without migration errors and every listed acceptance gate passes. Do not treat a responsive /health endpoint as migration or ingestion proof.
Rollback Routine
If a migration ran, do not start the old image against the migrated database. Restore the matched pre-upgrade backup into an isolated deployment with the prior Compose file, prior image digest, compatible TimescaleDB/Redis topology, and original secret set. The v2.0 release explicitly says the v1.5 backup is the escape hatch for that migration.
Example recovery outline (not performed):
# Stop the failed deployment and preserve it for diagnosis.
docker compose -f docker-compose.pg18.yml -f compose.override.yaml down
# Create a separate restore project using the recorded prior files and images.
mkdir -m 0750 "$HOME/tracearr-restore"
cd "$HOME/tracearr-restore"
# Place the reviewed prior Compose files, .env, and backup here.
# Follow Tracearr's current Backup & Restore procedure for that exact version.
Example expected result (not observed): the restored prior version starts with its matching database and secrets, the owner can authenticate, historical sessions are present, and a synthetic stream is ingested. Keep the failed deployment stopped and separate until the cause is understood.
What This Does Not Prove
This article has not been validated in a TechGeeks lab against Tracearr v2.1, the v1-to-v2 migration, or any media-server integration. One synthetic Direct Play event and one transcode would not establish production scale, retention sizing, universal client compatibility, geolocation accuracy, account misuse, or authority for automated stream termination. A successful health endpoint does not prove login, migrated user ownership, server connectivity, historical continuity, alert delivery, proxy correctness, backup validity, or restore.
Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| Tracearr will not start | Missing secret, database, Redis, permission, or migration failure. | docker compose ps, docker logs tracearr, docker logs tracearr-db, and docker logs tracearr-redis. |
| Login fails behind a proxy | Origin, forwarded host/protocol, secure-cookie, or proxy-trust mismatch. | Use one exact CORS_ORIGIN; preserve Host; verify X-Forwarded-Host, X-Forwarded-Proto, and trusted proxy scope. |
| Media server test passes but no sessions appear | Integration is reachable but playback events or polling do not match. | Run one synthetic stream, compare timestamps, Tracearr logs, and the media-server dashboard. |
| Jellyfin/Emby CPU and RAM charts are empty | Missing, old, or disconnected SSE plugin. | For Tracearr v2.1, verify Media-Server-SSE 0.4.0 or newer and inspect both plugin and Tracearr logs. |
| Transcode shown by one tool but not another | Timing, terminology, or event-field mismatch. | Compare the same session ID/time window with the media-server dashboard and transcoder log. |
| Geolocation looks wrong | VPN, carrier NAT, mobile routing, travel, or database error. | Treat location as context; do not punish a user from one inferred location. |
| Import skips records | Duplicate guard, timezone, identity mapping, unsupported fields, or prior import. | Compare bounded counts, source timezone, earliest/latest timestamps, and skip reasons. |
| Database will not start after changing Compose | A PostgreSQL 18 file was pointed at an old/incompatible volume. | Stop. Restore the prior database topology and matched backup; do not initialize over the old volume. |
Planned Evidence Checklist
- Planned lab run: create
artifacts/labs/tracearr-setup-monitoring-plex-jellyfin-emby/YYYY-MM-DD/with CPU, RAM, storage, network, OS, Docker, image digests, Compose hashes, media-server/plugin/client versions, UTC times, commands, and exit codes. - Planned positive paths: ingest one Direct Play and one transcode from disposable Plex, Jellyfin, and Emby endpoints using synthetic accounts and authorized media.
- Planned negative path: disconnect one server or use a deliberately invalid test token, preserve the real failure and alert behavior, correct it, and collect a new artifact.
- Planned rule proof: create an alert-only rule, capture its configuration and one matching event, and confirm that no stream termination action is enabled.
- Planned migration and restore: back up a sanitized pre-v2 database, rehearse the supported upgrade in isolation, verify identity/history counts, then restore the matched old version and database separately.
- Planned screenshots: capture redacted server connection, synthetic stream, alert-only rule, import preview/counts, backup, migration, and restore states at a fixed viewport.
- Required redaction review: remove usernames, IP addresses, locations, media titles, device names, tokens, secrets, hostnames, URLs, notification payloads, and metadata before publication.
Until these artifacts exist and pass review, this article remains documentation-backed. No planned stream, alert, migration, measurement, screenshot, or restore is an observed TechGeeks result.
FAQ
Does Tracearr replace Tautulli?
It can replace or supplement Tautulli depending on your needs. Treat it as a migration project, not a magic drop-in. Validate history import, active sessions, notifications, user data, and daily workflows before retiring Tautulli.
Should Tracearr be exposed to the internet?
Usually no. Tracearr is an admin and analytics dashboard. LAN, VPN, or tightly controlled reverse-proxy access is the safer default.
Should account-sharing rules terminate streams automatically?
Not at first. Start alert-only, validate geolocation and user behavior, then decide whether any automatic action is appropriate.
Can Tracearr help reduce transcoding?
Yes. It can show direct play vs transcode patterns, problematic clients, high-bandwidth sessions, and peak-time pressure. Use that evidence to tune Plex, client guidance, Tdarr output, and worker schedules.
Series Navigation
Related TechGeeks Reading
Tracearr is part of the TechGeeks Plex, Arr, and Tdarr homelab series. These companion articles fill in the surrounding architecture, security, storage, monitoring, and automation decisions.
- Jellyfin home media server: start here
- Jellyfin Docker setup and playback test
- Direct Play vs transcoding cheat sheet
- Monitoring and health checks
- Reverse proxy security
- Backups and disaster recovery
- Plex and Tdarr GPU strategy
- Media automation series hub
References
- Tracearr Docker Compose installation and backup guidance
- Tracearr environment variables, auth secrets, OIDC, and proxy configuration
- Tracearr rules and automation documentation
- Tracearr beta backup and restore documentation
- Tracearr v2.0.0 migration release notes
- Tracearr v2.1.0 stable release notes
- Tracearr stable and prerelease index
- Tracearr v2.1.0 PostgreSQL 18 Compose example
Need help applying this?
Bring TechGeeks into the real environment.
If you are working through this on a live network, WordPress site, Linux server, AI workflow, or PisoWiFi deployment, send the context and we can help turn it into a practical plan.


