cplieger/plex-exporter repository overview

⁠plex-exporter

See what your Plex server is doing in Grafana: sessions, libraries, bandwidth, transcoding.

⁠What it does

Connects to your Plex Media Server and exposes metrics (active sessions, library sizes, bandwidth, transcoding status) in a format that Prometheus can scrape and Grafana can visualize.

Key metrics exposed:

• Library duration, storage, and item counts (movies, episodes, tracks)
• Active session details (user, device, resolution, stream type)
• Transcode type detection (video/audio/both) and subtitle handling
• Session bandwidth and location (LAN/WAN)
• Host CPU and memory utilization (Plex Pass)
• Bandwidth transmission totals (Plex Pass)
• HTTP polling reachability
• Active transcode session count

⁠Why this design

• Polling /status/sessions for real-time session tracking: polls the Plex sessions API every 5s, so new sessions appear within seconds; the tracker prunes sessions after 60s of inactivity
• Single binary: direct dependencies are prometheus/client_golang and a few small helper libraries (see Dependencies⁠); everything else is the standard library
• Distroless and rootless: runs on gcr.io/distroless/static-debian13 as UID 65532 with no shell or package manager, minimizing attack surface
• Prometheus-native: exposes a standard /metrics endpoint that works with any Prometheus-compatible scraper and any Grafana dashboard, no custom visualization layer

⁠Limitations

• Plex Pass features degrade gracefully. Host CPU and memory utilization and the bandwidth counter come from statistics endpoints that only answer with Plex Pass, so those three series are absent until the endpoints have answered once; every other metric still works.
• Library item counts are cached. Episode, track, and item counts are refreshed every 15 minutes to avoid hammering the Plex API. Counts may lag slightly after large library scans.

⁠Pull

docker pull cplieger/plex-exporter:latest

Also published to ghcr.io/cplieger/plex-exporter with identical images and tags. Release versions are tagged vX.Y.Z alongside latest.

⁠Quick start

# Example compose for plex-exporter. See the README for all configuration options and hardening.
services:
  plex-exporter:
    image: ghcr.io/cplieger/plex-exporter:latest
    container_name: plex-exporter
    restart: unless-stopped

    environment:
      PLEX_URL: "http://plex:32400"  # full URL including scheme and port
      PLEX_TOKEN: "your-plex-token"  # admin token from Plex Web settings

    ports:
      - "9594:9594"

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Contributing⁠
• Releases and changelog⁠

⁠License

GPL-3.0-or-later. See LICENSE⁠. The image carries the license text of every bundled component under /usr/share/licenses/.

Third-party attributions are in THIRD_PARTY_NOTICES.md⁠.