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. CPU/memory utilization and bandwidth statistics require Plex Pass. Without it, those metrics are simply absent; 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.

Quick start

Available from both ghcr.io/cplieger/plex-exporter and docker.io/cplieger/plex-exporter; identical images and tags.

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"

Configuration reference

Environment variables

TLS / certificate setup

Pick the configuration that matches your Plex server:

Ports

Hardened and Kubernetes deployments

The health probe writes a marker file to /tmp/.healthy (see Healthcheck), so a read-only root filesystem needs a writable /tmp. Without one the probe can never pass and the container is reported unhealthy while the exporter itself works. A small in-memory mount is enough; the marker is an empty file.

Docker Compose:

    read_only: true
    tmpfs:
      - "/tmp:size=1m,mode=1777,noexec,nosuid,nodev"

Kubernetes, alongside securityContext.readOnlyRootFilesystem: true:

    volumes:
      - name: tmp
        emptyDir:
          medium: Memory
          sizeLimit: 8Mi
    # in the container spec
    volumeMounts:
      - name: tmp
        mountPath: /tmp

One more thing worth knowing on Kubernetes: the Prometheus Operator adds pod, endpoint and container labels to every scraped series, and the pod value changes on each restart. A panel reading a single gauge over a time range therefore renders one entry per dead pod until the old series ages out.

The shipped dashboard handles this by asking current-state tiles for an instant value rather than a range, so stale pod series cannot appear. If you need those labels gone at ingestion instead, drop them in the ServiceMonitor:

    metricRelabelings:
      - action: labeldrop
        regex: (pod|endpoint|container)

Do this only for a single-replica deployment. Those labels are what distinguishes one replica's series from another's, so dropping all three on a multi-replica ServiceMonitor makes two replicas emit identical label sets, which Prometheus warns against explicitly. With more than one replica, keep pod and aggregate in the query instead.

Metrics reference

HTTP Endpoints

Server Metrics

Library Metrics

Session Metrics

Session Label Reference

For episodes: title = show name, child_title = season, grandchild_title = episode title, grandchild_index = episode number (track number for music). For movies: title = movie name, others are empty.

Beyond the values above, every user-controlled label value is normalized to a bounded set, so an unexpected Plex response can never explode Prometheus cardinality: a value outside the documented set becomes other and missing data becomes unknown. This covers stream_type, media_type, location, subtitle_action, and the resolution labels. An empty Plex subtitleDecision is reported as subtitle_action="none".

Alerting

plex-exporter exposes Prometheus metrics on /metrics (see Metrics reference) and writes its own diagnostics to its container log. The rules ship as one file per expression language: scrape /metrics and evaluate the six PromQL rules in alerts/promql.yaml with Prometheus or the Mimir ruler, and ship the container's logs to Loki (Grafana Alloy's Docker log discovery does this with no configuration) to evaluate the three LogQL rules in alerts/logql.yaml with Loki's ruler. Load each half into its own ruler: neither ruler parses the other's expressions. Firing alerts deliver through your Alertmanager either way. They cover:

Thresholds, the for: windows, and the severity labels are starting points; add your scrape job label to the selectors if you run more than one instance, adjust the container selector to whatever your log collector sets, and route by whatever labels your Alertmanager uses.

PlexExporterTargetDown and PlexExporterTargetAbsent are the two rules that must carry a job matcher, because they ask whether this exporter is visible at all. Set both to whatever your scrape config calls the exporter, and keep the matcher exact rather than a regex: a regex asks whether any matching target is up, so one healthy replica masks a failed one, and it leaves the absent() result with no label to route on.

Every metric rule reads a series the exporter publishes, so all of them go quiet together when it stops being scraped, which is what those two rules exist to catch. The three log rules are the ones that still fire when there is nothing left to scrape: a configuration the exporter refuses outright reaches PlexExporterFatalError before any series exists.

Healthcheck

The image ships a HEALTHCHECK (the CLI probe /plex-exporter health) that verifies the HTTP server is listening; /api/health serves the same status over HTTP. The container exits (and Docker restarts it) only on a non-recoverable startup error: a bad token or other 4xx (except 408 and 429), the wrong server (404), a TLS/certificate misconfiguration, or a metrics-server start failure. A transient startup failure (DNS, dial, timeout, a 408 or 429, or a 5xx from a Plex that is still starting up) instead brings the exporter up degraded but healthy: it binds /metrics, reports plex_http_reachable=0, and recovers automatically once Plex is reachable again.

Security

Connects outbound to Plex only. The /metrics endpoint serves read-only Prometheus data (standard for internal exporters). PLEX_TOKEN is never logged or exposed in metrics.

The Plex client sends the token in a request header, refuses redirects, restricts requests to the configured server, bounds response reads, and caps each request at 30s. TLS verification always stays on; PLEX_CA_CERT_PATH pins a private CA instead of disabling it. Rating keys are validated as integers before URL construction, and the metrics server sets explicit read, write, and header timeouts. The image runs as a non-root user on a distroless base with no shell or package manager.

Static analysis and vulnerability scans run in CI on every change; current results are on the repository's Security tab. One accepted finding: semgrep reports two informational matches, both reviewed as false positives.

Dependencies

All dependencies are updated automatically via Renovate and pinned by digest or version for reproducibility.

Credits

This is an original tool building on the Grafana Hackathon 2022 prometheus-plex-exporter lineage: the @jsclayton post-hackathon fork and the actively maintained @timothystewart6 fork. It also uses the Plex Media Server API and prometheus/client_golang.

Contributing

Issues and pull requests are welcome. Please open an issue first for larger changes so the approach can be discussed before implementation.

Disclaimer

This project is built with care and follows security best practices, but it is intended for personal / self-hosted use. No guarantees of fitness for production environments. Use at your own risk.

This project was built with AI-assisted tooling using Claude, GPT, and Kiro. The human maintainer defines architecture, supervises implementation, and makes all final decisions.

License

GPL-3.0-or-later. See LICENSE.