v3.1.0: Add timeshift, channel, and plugin metrics; fix DB connection leak (#12)

Added

• Catch-up (timeshift) streams now show up alongside live and VOD everywhere: dispatcharr_active_streams{type="timeshift"}, dispatcharr_stream_metadata, dispatcharr_stream_active_clients, dispatcharr_stream_uptime_seconds, dispatcharr_stream_avg_bitrate_bps, and per-viewer dispatcharr_client_* connection metrics (client stats setting).
• Catch-up sessions report EPG program info just like live TV, anchored to the position being watched rather than real time; the current program title is prefixed Catchup-MM-DD-HH:MM: to distinguish it from a live view.
• Active M3U provider and profile (provider, provider_type, profile_id, profile_name) and connection limits are now reported for catch-up streams, matching live.
• New per-channel info metrics (dispatcharr_channel_info, dispatcharr_channel_source_count, dispatcharr_channel_catchup_days) covering channel group, source/stream count, and catch-up configuration, behind a new "Include Channel Info Statistics" setting.
• New plugin health metrics (dispatcharr_plugins, dispatcharr_plugin_info, dispatcharr_plugin_repos, dispatcharr_plugin_repo_info, dispatcharr_plugin_repo_last_fetch_timestamp) behind a new "Include Plugin Statistics" setting.

Fixed

• The metrics server now releases its database connection after every scrape. Previously it could leave connections open indefinitely, which under sustained load could exhaust the database's connection limit and make Dispatcharr unresponsive.

Dev Build (2d8bd771)

Dispatcharr Exporter dev build from the dev branch.

Field	Value
Description	Expose Dispatcharr metrics in Prometheus exporter-compatible format for monitoring
Author	sethwv
License	MIT
Min Dispatcharr	v0.22.0
Docs	https://github.com/swvn-dispatch/dispatcharr-exporter
Discord	https://discord.com/channels/1340492560220684331/1451260201775923421

v3.0.1: compatibility with live_proxy rename in new Dispatcharr versions (#10)

Fixed

• Compatible with Dispatcharr versions that renamed ts_proxy to live_proxy - the plugin now tries the new module path first and falls back to the old one, so both old and new Dispatcharr installs are supported

v3.0.0: User metrics, expanded type labels, legacy metric removal (#9)

Added

• User metrics: dispatcharr_user_info, dispatcharr_user_date_joined_timestamp, dispatcharr_user_stream_limit, and dispatcharr_user_active_streams (opt-in via new Include User Statistics setting)
• dispatcharr_m3u_account_info gauge providing metadata for each M3U account
• Per-type breakdown on dispatcharr_active_streams with type="live" and type="vod" labels
• type label added to dispatcharr_stream_fps, dispatcharr_stream_video_bitrate_bps, dispatcharr_stream_transcode_bitrate_bps, dispatcharr_stream_current_bitrate_bps, dispatcharr_stream_channel_number, dispatcharr_stream_index, and dispatcharr_stream_available_streams
• user_id and username labels on dispatcharr_client_info
• Manual stop flag - stopping the server now prevents auto-start from restarting it until explicitly started again

Changed

• Minimum Dispatcharr version raised to v0.22.0
• "Start Server" and "Restart Server" action buttons merged into a single "Start / Restart Metrics Server" button

Removed

• Legacy metrics (dispatcharr_stream_info, legacy dispatcharr_m3u_account_info with stream_count label, legacy dispatcharr_epg_source_info with priority label) and the Include Legacy Metric Formats setting
• Disable Update Notifications setting and the Check for Updates action button

v2.4.2

Fixed

• Prevent exporter auto-start from being blocked by stale state left behind after a failed upgrade or ungraceful shutdown by clearing prior Redis keys and removing the stale auto-start lock file on startup.

v2.4.1: Refactor error handling, logging, and improve plugin configuration (#6)

Added

• Modified plugin metadata to support upcoming plugin repo.
• Added stronger server stop reliability:
  • MetricsServer._verify_stopped() to confirm the port is actually free after stopping.
  • Stop-signal monitor now:
    • reuses a Redis client instead of reacquiring every loop iteration,
    • retries Redis acquisition if missing,
    • logs periodic “heartbeat” and escalates some logs to info/warning,
    • calls server.stop(timeout=5) and verifies shutdown.

Changed

• Auto-start lock handling tightened and made safer:
  • lock file permissions changed from 0666 to 0600 (owner-only).
  • explicit handling of BlockingIOError to exit cleanly when another worker owns the lock.
  • improved cleanup on exceptions (best-effort unlock/close).
  • removed the early _auto_start_attempted = True assignment (was being set before lock/auto-start logic ran).
• stop_server / restart_server actions improved for cross-worker scenarios:
  • more explicit logging when sending stop signals via Redis.
  • if shutdown isn’t confirmed within 5 seconds, force-cleans Redis keys (server_running, server_host, server_port, stop_requested) and removes the lock file so a restart can proceed.
• General code cleanup:
  • Removed unused typing import.
  • Replaced many silent pass blocks with commented pass explaining why an exception is ignored.
  • Minor trimming of unused local variables in VOD programming (removed unused rating/air_date vars).

v2.4.0

Added

• Unified live + VOD stream coverage for stream metrics via a new type label (type="live" / type="vod"), so the same metric families can represent both.
• Added VOD-aware stream enrichment:
  • dispatcharr_stream_metadata now includes VOD labels like content_uuid, content_type (movie/episode), and episode labels (season_number, episode_number, series_name) when available.
  • dispatcharr_stream_programming now supports VOD by emitting content title/description + a time-based progress value (elapsed/duration).
• Added dispatcharr_stream_buffering_speed gauge (live-only) derived from ffmpeg “speed” (e.g., 1.0x → 1.0).
• Added per-type active stream counts:
  • dispatcharr_active_streams{type="live"} and dispatcharr_active_streams{type="vod"}.
• Expanded client connection metrics to include VOD sessions as clients (with type="vod"), including:
  • dispatcharr_client_info
  • dispatcharr_client_connection_duration_seconds
  • dispatcharr_client_bytes_sent
  • dispatcharr_client_avg_transfer_rate_bps
  • dispatcharr_client_current_transfer_rate_bps

Changed

• Removed the separate “VOD Metrics” section/setting:
  • Dropped include_vod_stats setting and the dispatcharr_vod_* metrics.
  • VOD is now represented through the same stream/client metrics with type="vod".
• Updated profile connection counting logic to include both:
  • live channel streams (channel_stream:*)
  • VOD persistent connections (vod_persistent_connection:* with active_streams > 0)
• Improved MetricsServer host handling and diagnostics:
  • Normalizes empty/whitespace host values to default host
  • Logs exact bind target and validates host resolution (getaddrinfo) before binding, with clearer Docker guidance (0.0.0.0).
• Updated docs and samples:
  • METRICS.md reorganized (VOD section replaced with Client Connection Metrics) and updated queries/joins to include type.
  • Grafana dashboard + sample panels updated for Grafana 12.3.3, new Type column, and refreshed table options/layout.

Fixed

• Improved label escaping for VOD programming strings (ensures backslashes, quotes, and newlines are escaped in a safe order).
• Minor JSON formatting/EOF newline fixes in sample dashboard/panels.

Full Changelog: v2.3.0...v2.4.0

v2.3.0

This release requires >= v0.19.0 of Dispatcharr to run

Added

• Added a pre-built Grafana dashboard for quick import:
  • samples/dashboards/Dispatcharr-1767806789544.json (+ screenshot in samples/dashboards/images/Dispatcharr.png)
• Added src/plugin.json (plugin manifest) and src/logo.png to support Dispatcharr v0.19.0+ plugin system expectations.
• Release workflow now updates the version in both src/plugin.py and src/plugin.json.

Changed

• Moved plugin metadata/config to src/plugin.json and updated src/plugin.py to load config from that file (with a safe fallback config if loading fails).
• Updated packaging script to enforce/validate presence of src/plugin.json and to keep its version in sync during packaging.
• README now highlights dashboards (instead of individual example panels) and includes dashboard import instructions.
• Updated sample panel JSON (samples/panels/active-streams.json) to a newer table layout:
  • Adds “Program” and “Progress” (gauge) columns via merged Prometheus queries
  • Improves table styling (centered logos, stronger state row highlighting, column sizing)

Fixed

• Fixed Prometheus label escaping for program metadata (escape order corrected; now also escapes newlines), reducing the chance of producing invalid metrics output.
• Centralized Dispatcharr version detection into a single helper to keep version reporting and minimum-version checks consistent.
• Removed background auto-update notification thread logic; updates are now checked via the existing “Check for Updates” action button (reduces startup noise/side effects).

Full Changelog: v2.2.0...v2.3.0

v2.2.0: Channel Programming Exported Metric (#1)

NOTICE: If you are running Dispatcharr in Docker, add PYTHONDONTWRITEBYTECODE=1 to your container's environment variables to prevent root-owned cache files from blocking plugin updates. This is a workaround for a Dispatcharr startup behavior that runs migrations as root.

Added

• Added dispatcharr_stream_programming to expose current EPG program context (previous/current/next program details) and current-program progress for active streams.

---

Installing: https://github.com/sethwv/dispatcharr-exporter?tab=readme-ov-file#installation
Upgrading: https://github.com/sethwv/dispatcharr-exporter?tab=readme-ov-file#updating-the-plugin
Full Changelog: v2.1.1...v2.2.0

v2.1.1

NOTICE

Important: If you are running Dispatcharr in Docker, add PYTHONDONTWRITEBYTECODE=1 to your container's environment variables to prevent root-owned cache files from blocking plugin updates. This is a workaround for a Dispatcharr startup behavior that runs migrations as root.

Added

• (v2.1.1 HOTFIX) New stream metric:
  • dispatcharr_stream_current_bitrate_bps — Current bitrate in bits per second (sum of all connected client transfer rates). Matches the "current bitrate" shown in Dispatcharr UI.
• Minimum Dispatcharr version check:
  • Plugin now verifies that Dispatcharr meets the minimum required version (v0.14.0) at startup.
  • Skips version check for dev builds (with timestamp suffix).
  • Logs warning if version cannot be determined and proceeds anyway.
• Profile expiry metric:
  • New dispatcharr_profile_days_to_expiry gauge showing days remaining until XC profile expiry.
  • Value is 0 if expired, -1 if no expiry is set.
  • Calculated from custom_properties['user_info']['exp_date'] Unix timestamp.
• Root-owned __pycache__ detection:
  • Plugin detects root-owned __pycache__ directories at startup (caused by Dispatcharr running migrations as root).
  • Logs a warning with remediation instructions (add PYTHONDONTWRITEBYTECODE=1 or manually delete).

Changed

• (v2.1.1 HOTFIX) Client transfer rate unit auto-detection:
  • Client metrics now auto-detect whether Redis fields contain bytes/s or KB/s (field names suggest KB/s but currently contain bytes/s in some Dispatcharr versions).
  • Auto-detection logic: if value > 50000, assume bytes/s; otherwise assume KB/s.
  • Applied to both avg_rate_KBps and current_rate_KBps fields.
• Bitrate metrics now use bits per second (bps) instead of kilobits per second (kbps):
  • Stream metrics: dispatcharr_stream_video_bitrate_bps, dispatcharr_stream_transcode_bitrate_bps, dispatcharr_stream_avg_bitrate_bps (previously *_kbps).
  • Client metrics: dispatcharr_client_avg_transfer_rate_bps, dispatcharr_client_current_transfer_rate_bps (previously *_kbps).
  • All bitrate values are now in bits per second for consistency with Prometheus/Grafana best practices.
  • Use Grafana's "bits/sec" unit for automatic formatting (auto-converts to Kbps, Mbps, Gbps).
  • Legacy metrics also updated to use *_bps naming and values.
• Profile connection counting improved:
  • Profile connection metrics now calculate actual active connections by scanning active streams.
  • More accurate than Redis counters which don't update during stream fallback/failover.
• METRICS.md documentation updated:
  • All bitrate metric names and examples updated to reflect bps units.
  • Added PromQL examples for converting bps to Mbps for display.

Fixed

• (v2.1.1 HOTFIX) Client transfer rates now correctly handle Dispatcharr versions that store bytes/s instead of KB/s in Redis fields (previously multiplied by 8000 unconditionally, causing 1000x inflation).
• Profile connection metrics now reflect reality during stream fallback (previously used stale Redis counters).

---

Installing: https://github.com/sethwv/dispatcharr-exporter?tab=readme-ov-file#installation
Upgrading: https://github.com/sethwv/dispatcharr-exporter?tab=readme-ov-file#updating-the-plugin
Hotfix Changelog: v2.1.0...v2.1.1
Full Changelog: v2.0.0...v2.1.1