v3.0.0

3.0.0 (2026-06-13)

Highlights

• Metrics now follow Prometheus naming & typing best practices. Units are in the metric name as base units (_bytes, _seconds), percentages are exposed as ratios in 0–1 (_ratio), and descriptive attributes use the info-metric pattern.
• Base units everywhere. Memory, file sizes, and size-diff are now _bytes (was _mb/_gb); stream duration is _seconds. Values are rescaled accordingly — dashboards format human-readable automatically.
• Ratios instead of percentages. Score, health-check score, host CPU, and worker progress are now 0–1 ratios (_ratio). Use Grafana's percentunit unit to display as %.
• library_name moved to an info metric. Per-library v the stable library_id; the human-readable name is exposedonce via tdarr_library_info{library_id, library_name}. This keeps a library rename from breaking historical series.
• Worker attributes split into their own metrics. workle are no longer labels on tdarr_node_worker_info — theyare now dedicated metrics keyed on worker_id, so high-churn status values no longer inflate the info series.
• New server health & status metrics: tdarr_server_healthy, tdarr_server_info, tdarr_server_status_info, tdarr_server_uptime_seconds.
• Honest counter vs gauge typing. Per-library lifetime tallies are counters (_completed_total); the global lifetime tallies are gauges, because they can decrease when files are purged from Tdarr (see migration note below).
• Reworked Grafana dashboard with a clean split between server-wide Overview panels and per-$library panels. Re-import required (see below).

Migration guide

v3.0.0 is a breaking release: most metrics are renamed and/or retyped to follow Prometheus conventions. There is no compatibility shim — update
your queries, alerts, and dashboards. Re-import the bundled

Renamed — unit in name → base unit (values rescaled)

v2.x	v3.0.0	Notes
tdarr_node_heap_total_mb	`tdarr_node_heap_total_bytes
tdarr_node_heap_used_mb	tdarr_node_heap_used_bytes	MB → bytes
tdarr_node_host_mem_total_gb	tdarr_node_host_mem_total_bytes	GB → bytes
tdarr_node_host_mem_used_gb	`tdarr_node_host_mem_used
tdarr_node_worker_est_file_size_gb	tdarr_node_worker_est_file_size_bytes	GB → bytes
tdarr_node_worker_original_file_size_gb	tdarr_node_worker_original_file_size_bytes	GB → bytes
tdarr_node_worker_output_file_size_gb	`tdarr_node_wor GB → bytes
tdarr_size_diff_gb	tdarr_size_diff_bytes	GB → bytes; signed, positive = space saved
tdarr_library_size_diff_gb	tdarr_library_size_diff_bytes	GB → bytes; signed, positive = space saved
tdarr_stream_stats_duration	tdarr_stream_stats_duration_seconds	rename only (already seconds)

tdarr_stream_stats_bit_rate is intentionally left in bits/sec — bits is the conventional unit for video bitrate.

Renamed — percent → ratio (values divided by 100, now 0–1)

v2.x	v3.0.0
tdarr_score_pct	tdarr_score_ratio
tdarr_health_check_score_pct	tdarr_health_check_score_ratio
tdarr_node_host_cpu_percent	tdarr_node_host_cpu_ratio
tdarr_node_worker_percentage	tdarr_node_worker_ratio

In Grafana, set the panel unit to percentunit (which expe any max: 100.

Renamed / retyped — counts & lifetime tallies

v2.x	v3.0.0	Type	Notes
tdarr_files_total	tdarr_files	gauge	current inventory count, not a counter
tdarr_library_files_total	tdarr_library_files	gau
tdarr_transcodes_total	tdarr_transcodes_completed	gauge	global live aggregate; can decrease when files are purged
tdarr_health_checks_total	tdarr_health_checks_completed	gauge	global live aggregate; can decrease when files are purged
tdarr_library_transcodes_total	tdarr_library_transcodes_completed_total	counter	per-library, sticky/monotonic
tdarr_library_health_checks_total	tdarr_library_health_checks_completed_total	counter	per-library, sticky/monotonic

Why the global totals are gauges, not counters: the global tdarr_transcodes_completed / tdarr_health_checks_completed reflect lifetime events of files currently present in Tdarr, so they step down when a file is deleted (verified against the live API). That violates counter monotonicity and would make rate()/increase() emit phantom spikes. For a monotonic rate, use the per-library tdarr_library_*_completed_total counters (these never decrease).

Renamed — worker step timestamp

v2.x	v3.0.0
tdarr_node_worker_start_timestamp_seconds	tdarr_node_worker_step_start_timestamp_seconds

Removed

v2.x	Notes
tdarr_node_worker_pid	Removed — newer Tdarr API versions no longer expose a worker process id. There is no replacement. (Note:
tdarr_node_info carries a node_pid label, but that is t the worker's.)

Label changes (query-breaking, even where the metric name is unchanged)

• **library_name removed from all tdarr_library_* metrilibrary_id. The name is exposed once via the newtdarr_library_info{library_id, library_name}`. Join it back in:
  • Add the name to results: tdarr_library_transcodes_completed_total * on (library_id, tdarr_instance) group_left(library_name) tdarr_library_info
  • Filter by name: tdarr_library_files and on (library_id, tdarr_instance) tdarr_library_info{library_name=~"Movies"}
• Worker attributes split off tdarr_node_worker_info into dedicated metrics keyed on worker_id: tdarr_node_worker_status (carries the worker_status label), tdarr_node_worker_plugin, and tdarr_node_worker_idle. tdarr_node_worker_info is now identity-only. Join on worker_id if you need to combine them.

Dashboard

Re-import the bundled Grafana dashboard (examples/dashboarn's queries reference the old metric names and will notrender against v3.0.0. If you are staying on an older exporter, compatible dashboards are archived at examples/archive/dashboard.v2.json (v2.X.X) and examples/archive/dashboard.v1.json (v1.X.X`).

⚠ BREAKING CHANGES

• the library_name label is removed from all tdarr_library_* metrics. Recover it by joining on library_id against the new tdarr_library_info{library_id, library_name} metric, e.g. tdarr_library_files * on (library_id) group_left(library_name) tdarr_library_info. Dashboards and alert rules that selected or grouped by library_name must be updated to join through tdarr_library_info (see examples/dashboard.json and examples/alerts.yaml).
• tdarr_score_pct, tdarr_health_check_score_pct, tdarr_node_host_cpu_percent and tdarr_node_worker_percentage are renamed to _ratio and now expose 0-1 values instead of 0-100. Update queries, alerts and dashboard panels accordingly.
• metric names and value scales changed; update dashboards and recording/alerting rules referencing the old *_mb/_gb names.
• tdarr_node_worker_start_timestamp_seconds renamed to tdarr_node_worker_step_start_timestamp_seconds. Disambiguates from the sibling job-start timestamp; "step" covers both classic plugin steps and flow steps.
• metric names and types changed; dashboards/alerts/recording rules referencing the old names must be updated.
• tdarr_node_worker_info no longer carries worker_status, worker_plugin_id, worker_plugin_position, or worker_idle labels. Queries and dashboards must read these from the new tdarr_node_worker_status, tdarr_node_worker_plugin, and tdarr_node_worker_idle metrics.
• tdarr_scrape_requests_total is removed. Queries/alerts must move to promhttp_metric_handler_requests_total (same {code} label). The "Handler Errors (5m)" dashboard panel is repointed accordingly.

Features

• add build_info metric and --version via prometheus/common/version (fd05d8f)
• add ErrUpstream/ErrParse sentinels for collection failure causes (f31e50c)
• add Exporter Internals panels and split Scrape Health row (08f0e6f)
• add GPU Select panel and clarify node panels (ca012f8)
• add GPU Select panel and dashboard layout pass (90871fe)
• add tdarr_server_healthy gauge and server info dashboard panels (4f9255e)
• add TdarrServerStatus model for /api/v2/status (b391a0e)
• add TdarrStatusPath config for /api/v2/status endpoint (1a1c282)
• canonical promhttp handler metrics + Exporter Internals dashboard (2f026fa)
• convert size/heap/mem metrics to base-unit bytes, duration to seconds (b3b645b)
• emit canonical promhttp handler metrics with tdarr_instance (03a557d)
• emit tdarr_library_audio_resolutions metric (7b7d042)
• expose go/process runtime metrics; modernize interface{} to any (96431cc)
• fetch /api/v2/status and emit server uptime/info/status metrics (0633bcd)
• migrate releases to release-please (7de843d)
• migrate releases to release-please (21f8300)
• move library_name to tdarr_library_info, key library metrics on library_id (b87a834)
• propagate context through scrape for shutdown cancellation (e2960e9)
• register server status/info/uptime descs in collector (3cd5b1c)
• rename percent metrics to _ratio (0-1), fix worker-table byte units (89a7ad8)
• rename worker step-start metric, fix size-diff semantics, surface orphan metrics (1863480)
• rename/retype *_total metrics for Prometheus naming (P3.1) (2c75f04)
• split worker status/plugin/idle off node_worker_info (da84617)
• Tdarr server status metrics + dashboard panels (e6e210c)

Bug Fixes

• check Close() errors in tests to satisfy errcheck lint (37d6116)
• classify post-retry 4xx/3xx as errors and detect URL scheme via :// (ee9a31f)
• clone HTTP transport, guard cache read, make retry testable (912d121)
• close discarded response bodies in retry transport (b407831)
• collapse ci test pass into single test_all task (50cda1b)
• correct library_audio_containers metric help text (c859d6e)
• drop tdarr_library_audio_resolutions; Tdarr audio pie has no resolutions (bc37029)
• harden CI, build flags, and dev tooling (c25daae)
• harden CI, build flags, and dev tooling (22b690f)
• harden renovate config (42e0915)
• harden renovate config (79f79d8)
• namespace Taskfile tasks with colon grouping (d9301d5)
• propagate server errors instead of os.Exit in goroutine (15454b7)
• recover from scrape panics, degrade to tdarr_up=0 (d2a9267)
• recover from scrape panics, degrade to tdarr_up=0 (507d79f)
• remove dead tdarr_node_worker_pid metric (8a26beb)
• remove dead tdarr_node_worker_pid metric (de377b7)
• remove duplicate root renovate.json (385816c)
• remove duplicate root renovate.json (996613a)
• run go mod tidy for renovate updates (07a274e)
• run go mod tidy for renovate updates (091694b)
• scope transcode-failed alert join to include tdarr_instance (2b22d59)
• split File Descriptors panel into used-vs-limit graph + %-of-limit stat (4b7ec80)
• split File Descriptors panel into used-vs-limit graph + %-of-limit stat (f2a1973)
• use default-action + subcommand task naming (dd32ca3)

Code Refactoring

• drop redundant tdarr_scrape_requests_total (b976fe2)