Server Telemetry

When you turn telemetry on, QuickBox Pro sends system metrics from your server to your QuickBox account so you can monitor it from anywhere. Telemetry is off by default on new installs. This page explains what is sent, why it’s useful, and how to turn it on or off.

What is Telemetry?

Telemetry is the automatic collection and transmission of system metrics from your QuickBox Pro server to your dashboard. This allows you to monitor your server’s health, resource usage, and user activity from anywhere.

While telemetry is on, QuickBox Pro sends metrics via the heartbeat system every 5 minutes by default to keep your account dashboard up to date. While it is off, nothing is sent and the heartbeat does not run.

What Data is Collected

System Metrics

• CPU - Processor name, core count, frequency, and usage percentage
• Memory - Total RAM, used RAM, and free RAM
• Disk Space - Total disk space, used space, and free space
• Network - Interface name, monthly RX/TX totals, and current RX/TX speeds
• Speed Test - Your server’s latest network speed test result: download and upload throughput (Mbps), ping and jitter (ms), the speed test tool used, and when the test ran. Sent only if a speed test has been run on the server.
• Uptime - How long the server has been running
• Load Average - 1-minute, 5-minute, and 15-minute load averages

Server Information

• Hostname - Your server’s hostname
• IP Addresses - Server’s public and local IP addresses
• OS Info - Operating system and version
• Server Version - The QuickBox Pro CLI Core version number
• Dashboard Version - The QuickBox Pro UI Dashboard version, when one is installed
• License Key and Instance ID - Identify your license and this server so the heartbeat can be authenticated
• Seats Used - The number of user accounts on the server

User Activity

• User List - Usernames and email addresses of QuickBox users
• Last Login - When each user last logged in
• Active Status - Whether each user account is active
• Pending Application Updates - For each user, the applications with an update waiting, with the installed and available versions

What is NOT Collected

We do not collect:

• File names, directories, or file contents
• Configuration files or settings
• Passwords or authentication tokens
• Personal media libraries or torrents
• Browsing history or activity logs
• Hardware serial numbers
• Your media consumption habits

Why is Telemetry Useful?

Real-time Monitoring - Check your server’s status from your dashboard anytime, anywhere.

Resource Planning - Track CPU, RAM, and disk usage trends over time to plan upgrades.

Update Notifications - See which applications have updates available at a glance.

User Management - Monitor user activity and last login times.

Troubleshooting - Diagnose performance issues remotely without SSH access.

Capacity Planning - Know when to upgrade before running out of resources.

Where to See Your Telemetry

1. Sign in at quickbox.io. This is where every QuickBox account lives. If you came from the previous QuickBox site, sign in with the same email and password.
2. Open Licenses in the sidebar, under License Management. The Licenses page shows your license, its API keys, and a Servers table with the servers that license runs. If your account holds more than one license, pick the one you want first.
3. Open the license’s detail page. Select Telemetry on a server row, or Telemetry and details on the license card. Either opens License Details at /dashboard/licenses/<licenseId>. The Telemetry button on a server row opens that server’s row for you.
4. Find “Server Activations”. Each server is a row. Select the row, or the arrow at its end (“Show details”), to open it in place and read its telemetry.

The refresh icon beside the “Server Activations” heading (“Refresh telemetry data”) reloads the latest data straight away. The page also refreshes itself every 30 seconds while the license grants access and has an active API key. It does not make the server send a heartbeat. “Last updated” shows when the page last read the data.

If telemetry is off for the license, the servers are not monitored and the refresh icon is disabled. See Turning Telemetry On or Off to switch it on from the server.

Per-server telemetry

When you open a server under Server Activations you’ll see:

• Identity band – when the server was activated, its last check, the check count, its instance ID, IP address, telemetry hostname, OS and QuickBox versions.
• System telemetry – server status with uptime, and, while the server is online, load average, CPU, memory, disk and network. A card appears only when the server reports that value.
• Connection history – select View History to open a timeline of when the server was online and offline. You can tick entries and clear them, or clear all finished entries. The entry for the current session is kept.
• Active users – shown while the server is online. Each QuickBox user on the server with their last login and any application updates waiting for them.

The portal side of this, including naming a server and deactivating one, is explained in Servers and activations.

How Does It Work?

1. Cron Job - A cron job runs every 5 minutes (*/5 * * * *)
2. Data Collection - QuickBox Pro gathers system metrics
3. API Request - Data is sent to /api/v1/license/heartbeat via HTTPS
4. Dashboard Display - Metrics appear in your license dashboard in real-time

Security & Privacy

Turning Telemetry On or Off

Use the toggle in the Telemetry panel under System > API Control in the dashboard, or run:

qb manage telemetry -o on
qb manage telemetry -o off
qb manage telemetry -o status

The Telemetry panel can also show the exact data your server would send (Preview Payload), and Send Test sends one heartbeat immediately.

Technical Implementation

Cron Job

The heartbeat is triggered by a cron job that runs every 5 minutes by default. The entry stays commented out in /etc/cron.d/quickbox until telemetry is turned on:

*/5 * * * * root /usr/local/bin/qb manage api -o heartbeat --cron >/dev/null 2>&1

API Endpoint

Data is sent to:

POST /api/v1/license/heartbeat

Request Format

{
  "license_key": "your-license-key",
  "instance_id": "your-instance-id",
  "hostname": "server.example.com",
  "os_info": "Ubuntu 22.04 LTS",
  "server_version": "3.2.2.8903",
  "dashboard_version": "4.0.1.3760",
  "cpu_name": "Intel Xeon E5-2680 v4",
  "cpu_cores": 28,
  "cpu_frequency": "2.40 GHz",
  "cpu_usage": 15.3,
  "memory_total": 67108864,
  "memory_used": 45088768,
  "memory_free": 22020096,
  "disk_total": 1073741824,
  "disk_used": 536870912,
  "disk_free": 536870912,
  "uptime": 1234567,
  "load_average_1": 1.2,
  "load_average_5": 1.5,
  "load_average_15": 1.8,
  "server_public_ip": "203.0.113.10",
  "server_local_ip": "192.168.1.10",
  "network_interface": "eth0",
  "network_rx_month": 1099511627776,
  "network_tx_month": 549755813888,
  "network_rx_speed": 125000000,
  "network_tx_speed": 125000000,
  "network_test_download_mbps": 942.7,
  "network_test_upload_mbps": 918.3,
  "network_test_ping_ms": 4.2,
  "network_test_jitter_ms": 0.6,
  "network_test_engine": "librespeed-cli",
  "network_test_at": "2025-11-23T09:15:00Z",
  "seats_used": 1,
  "users": [
    {
      "username": "alice",
      "email": "alice@example.com",
      "is_active": true,
      "last_login": "2025-11-23T10:30:00Z",
      "software_updates": {
        "radarr": { "current": "5.14.0.9383", "available": "5.15.1.9428" },
        "sonarr": { "current": "4.0.10.2544", "available": "4.0.11.2680" }
      },
      "software_updates_count": 2
    }
  ]
}

Frequently Asked Questions