qBittorrent Metrics Exporter

I created this project to get more detailed metrics from my qBittorrent instances for my Grafana dashboards. It's a Prometheus exporter that collects a wide range of stats and provides powerful aggregation by both category and tag.

It has two backend modes: a simple in-memory one for live data, and a PostgreSQL backend for keeping a permanent history of your torrents.

Key Features

• Dual Backend System: Choose between real-time in-memory stats or a persistent PostgreSQL database for historical data.
• Multi-Instance Monitoring: Scrape metrics from multiple qBittorrent instances with a single exporter.
• Rich, Labeled Metrics: Gathers a wide variety of stats, all labeled with host, hash, name, and category for easy filtering.
• Category & Tag Aggregation: Automatically calculates and exposes total counts, sizes, and traffic for each category and tag you use.
• Detailed NixOS Module: As a NixOS user, I've included a comprehensive module to make deployment easy and declarative.

Backends Explained

The backend determines how metric data is stored. You can choose one based on your needs.

In-Memory Backend (Default)

This is the standard, lightweight mode. It fetches the latest stats from qBittorrent and holds them in memory for Prometheus to scrape. Data is refreshed on each scrape and is gone when the exporter restarts. Perfect for live dashboards.

Database Backend

This mode is for keeping long-term statistics. It connects to a PostgreSQL database and saves torrent metrics on every scrape. It will add new torrents and update existing ones, but it never deletes a torrent. This allows you to build a complete history, even for items you've removed from your client.

Installation

From Crates.io

cargo install qbittorrent-metrics-exporter

NixOS

First, add the exporter flake to your flake.nix:

# flake.nix
{
  inputs = {
    # ... your other inputs
    
    # Add this line
    qbittorrent-metrics-exporter.url = "github:anriha/qbittorrent-metrics-exporter";
  };

  outputs = { self, nixpkgs, qbittorrent-metrics-exporter, ... }@inputs: {
    nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
      # ...
      modules = [
        # Add this to your list of modules
        qbittorrent-metrics-exporter.nixosModules.default
        ./configuration.nix
      ];
    };
  };
}

Then, enable and configure the service in your configuration.nix.

Example 1: Standard In-Memory Setup

# configuration.nix
services.prometheus.exporters.qbittorrent = {
  enable = true;
  # List all your qBittorrent instances here
  qbittorrentHosts = [ "http://192.168.1.10:8080" ];
  qbittorrentUsername = "your_username";
  # Recommended: use a file for your password to keep it safe.
  qbittorrentPasswordFile = "/path/to/your/qbit-password.txt";
};

Example 2: Database Backend Setup

For this, you'll need a PostgreSQL server and have a user/database prepared for the exporter.

# configuration.nix
services.prometheus.exporters.qbittorrent = {
  enable = true;
  backend.type = "database";
  
  # The default databaseUrl is for a local socket, but using a
  # secrets file for the full connection string is a good practice.
  backend.databaseUrlFile = "/path/to/your/db-connection-string.txt";
  
  qbittorrentHosts = [ "http://localhost:8080" ];
  qbittorrentUsername = "your_username";
  qbittorrentPasswordFile = "/path/to/your/qbit-password.txt";
};

The db-connection-string.txt file should contain the URL, e.g., postgres://user:password@host:port/database.

Configuration

The application can be configured via command-line arguments or the corresponding environment variables.

Exposed Metrics

A variety of metrics are available at the /metrics endpoint.

• Real-time Metrics: qbit_upspeed, qbit_dlspeed, qbit_num_leechs, etc.
• Historical/Counter Metrics: qbit_uploaded, qbit_downloaded, qbit_ratio, qbit_size, qbit_time_active.
• Aggregates by Category: qbit_category_count, qbit_category_size, qbit_category_uploaded.
• Aggregates by Tag: qbit_tag_count, qbit_tag_size, qbit_tag_uploaded.

Prometheus Integration

Add the following job to your prometheus.yml to start scraping:

scrape_configs:
  - job_name: "qbittorrent"
    scrape_interval: 60s
    static_configs:
      - targets: ["exporter-host:8000"]

License

This project is licensed under the GNU GPLv3.