Dashboard & Monitoring

The BitBonsai dashboard provides comprehensive system monitoring, job tracking, and performance analytics in a single unified view.

What is the dashboard? The main screen showing all your encoding activity, queue status, and system health in real-time.

Dashboard Overview

Access the dashboard at the main application page after login. The interface is organized into panels showing system health, active jobs, queue status, and performance metrics.

System Health

CPU, memory, and database status checks

Active Jobs

Real-time encoding progress tracking

Queue Status

Pending jobs and estimated completion

Performance

Throughput, savings, and efficiency metrics

Active Jobs Panel

Shows encoding tasks currently being processed across all nodes.

Job Information Display

Field	Description
File Name	Media file being encoded (e.g., `Movie.2024.1080p.mkv`)
Progress	Encoding completion percentage (0-100%)
Speed	Current encoding speed (fps - frames per second)
Node	Which node is processing this job (hostname or IP)
Stage	Current job stage: `ENCODING`, `ANALYZING`, `TRANSFERRING`
ETA	Estimated time remaining for completion

Progress Indicators

Active jobs display real-time progress bars:

Green bar: Encoding progressing normally (>5 fps)
Yellow bar: Slow encoding (1-5 fps, CPU-only nodes)
Red bar: Stalled job (no progress for >10 minutes)

Example display:

┌─────────────────────────────────────────────────────────────┐
│ Active Jobs (3)                                              │
├─────────────────────────────────────────────────────────────┤
│ Movie.2024.1080p.mkv                          [Main Node]   │
│ ████████████████░░░░░░░░░░ 67%    24.5 fps    ETA: 12m     │
│                                                              │
│ Series.S01E05.mkv                             [Node-170]    │
│ ████████░░░░░░░░░░░░░░░░░░ 35%    18.2 fps    ETA: 28m     │
│                                                              │
│ Documentary.2024.mkv                          [Main Node]   │
│ ███░░░░░░░░░░░░░░░░░░░░░░░ 12%    31.8 fps    ETA: 45m     │
└─────────────────────────────────────────────────────────────┘

Node Assignment

Each job shows which node is processing it. This helps identify:

Load distribution across nodes
Node performance differences (GPU vs CPU)
Potential bottlenecks (one node handling too many jobs)

Queue Status

Pending Jobs

Shows jobs waiting to be processed:

Metric	Meaning
QUEUED	Jobs waiting for available node capacity
PENDING	Jobs discovered but not yet queued (awaiting library scan)
ANALYZING	Files being analyzed for codec/bitrate information

Estimated Completion Time

Calculated based on:

Current throughput: Average jobs completed per hour (last 24h)
Queue depth: Total jobs in QUEUED and ANALYZING stages
Active workers: Number of concurrent encoding processes

Formula:

ETA = (QUEUED jobs + ANALYZING jobs) / throughput_per_hour

Example:

┌─────────────────────────────────────────────┐
│ Queue Status                                │
├─────────────────────────────────────────────┤
│ Pending Jobs:        142                    │
│ Active Workers:      3                      │
│ Avg Throughput:      12.5 jobs/hour         │
│ Est. Completion:     ~11 hours              │
└─────────────────────────────────────────────┘

System Stats

CPU Usage

Current Load: 1-minute load average
CPU Cores: Total cores available for encoding
Load Ratio: Load per core (ideal: under 1.5, warning: over 1.5, critical: over 2.0)

Health Indicators:

Status	Load Ratio	Color
Healthy	0.0 to 1.5	Green
Warning	1.5 to 2.0	Yellow
Critical	>2.0	Red

Memory Usage

Used/Total: Memory consumption (e.g., 12.4 GB / 16 GB)
Percentage: Memory utilization (warning at >85%, critical at >95%)
Trend: Memory usage over time (chart)

Disk Space

Shows storage statistics for all configured library paths:

Path	Total	Used	Free	Used %
`/mnt/media/movies`	4 TB	2.8 TB	1.2 TB	70%
`/mnt/media/tv`	2 TB	1.5 TB	500 GB	75%
`/mnt/media/anime`	1 TB	800 GB	200 GB	80%

Low Disk Space: When any path exceeds 90% usage, encoding may fail if output file cannot be written. BitBonsai needs temporary space (see temporary files).

Node Status

Health Indicators

Each node displays a status badge:

🟢 ONLINE: Node is healthy and accepting jobs
🔴 OFFLINE: Node unreachable or not responding to health checks
🟡 DEGRADED: Node online but experiencing high load or errors

Active Jobs Per Node

Track workload distribution across your encoding cluster:

┌─────────────────────────────────────────────────────────┐
│ Node Status                                             │
├─────────────────────────────────────────────────────────┤
│ Main Node (192.168.1.100)          [ONLINE]   2 jobs   │
│ GPU: NVIDIA GeForce RTX 3060                            │
│ Load: 1.2 / 4 cores    Memory: 8.5 GB / 16 GB          │
│                                                         │
│ Child Node (192.168.1.170)         [ONLINE]   1 job    │
│ GPU: Intel QuickSync (QSV)                              │
│ Load: 0.8 / 2 cores    Memory: 3.2 GB / 8 GB           │
└─────────────────────────────────────────────────────────┘

Load Distribution

Shows how jobs are distributed across nodes:

Main node: Primary encoding node (usually GPU-accelerated)
Child nodes: Worker nodes for parallel processing
Balanced: Jobs distributed evenly based on node capacity
Overloaded: One node handling disproportionate workload (>2x average)

Ideal distribution:

Main Node:    ████████████ 45% (4 jobs)
Child Node 1: ███████████ 35% (3 jobs)
Child Node 2: ████████ 20% (2 jobs)

Job History

Completed Jobs (Last 30 Days)

Shows encoding activity over the past month:

Date	Jobs Completed	Space Saved	Avg Speed
Jan 10	15	12.5 GB	22.3 fps
Jan 09	18	15.2 GB	24.1 fps
Jan 08	12	9.8 GB	21.7 fps
Total	424	488.3 GB	23.2 fps

Failed Jobs

Track encoding failures to identify problematic files:

File	Reason	Node	Date
`Corrupted.mkv`	File validation failed	Main	Jan 10
`LargeFile.mkv`	Insufficient disk space	Node-170	Jan 09
`BadCodec.avi`	Unsupported codec	Main	Jan 08

Failure Categories:

Corrupted File: Source file is damaged or incomplete (40%)
Disk Space: Insufficient storage for output file (25%)
Codec Issues: Unsupported or proprietary codec (20%)
FFmpeg Errors: Encoding process crashed (10%)
Other: Miscellaneous errors (5%)

Auto-Retry: Failed jobs are automatically retried up to 3 times with different encoding settings before being marked as permanently failed.

Performance Metrics

Average Encode Speed (fps)

Frames per second processed by the encoding engine:

Hardware	Typical Speed	Use Case
NVIDIA GPU	40-80 fps	HEVC/AV1 encoding
Intel QSV	20-40 fps	HEVC encoding
AMD GPU	25-50 fps	HEVC encoding
CPU-only	3-8 fps	Fallback for unsupported hardware

Factors Affecting Speed:

Resolution: 4K files encode slower than 1080p (~60% speed reduction)
Codec: AV1 is ~40% slower than HEVC, HEVC is ~30% slower than H.264
Bitrate: Higher bitrate source files take longer to process
Concurrent Jobs: Multiple jobs share GPU/CPU resources

Storage Saved

Total space saved by re-encoding to HEVC/AV1:

┌─────────────────────────────────────────────┐
│ Storage Savings                             │
├─────────────────────────────────────────────┤
│ Total Saved:        488.28 GB               │
│ Files Processed:    1,247                   │
│ Avg Savings:        35.2% per file          │
│ Equivalent to:      ~156 HD movies freed    │
└─────────────────────────────────────────────┘

Savings by Codec Conversion:

From → To	Avg Savings	Quality Impact
H.264 → HEVC	40-50%	Visually identical (same CRF)
H.264 → AV1	50-60%	Slightly better
HEVC → AV1	20-30%	Marginal improvement

Total Encoding Time

Cumulative time spent encoding across all nodes:

CPU Time: Total processing time (sum of all node hours)
Wall Time: Real-world time elapsed (accounts for parallel processing)
Efficiency: CPU Time / Wall Time (ideal: close to node count)

Example:

Total CPU Time:   142 hours
Wall Time:        48 hours
Nodes Used:       3
Efficiency:       2.96x (close to ideal 3.0x)

Efficiency Indicators:

over 2.5x (3 nodes): Excellent parallelization
1.5 to 2.5x (3 nodes): Good, some bottlenecks
under 1.5x (3 nodes): Poor distribution, investigate load balancing

Advanced Monitoring

Codec Distribution

See /insights/codecs endpoint for codec usage analytics:

Pie chart showing H.264, HEVC, AV1, VP9 distribution
Percentage of library using each codec
Helps identify remaining H.264 files to convert

Savings Trend (30-Day)

Track space savings over time:

Daily savings bar chart
Cumulative savings line graph
Identify encoding velocity (GB saved per day)

Node Performance Comparison

Compare encoding efficiency across nodes:

Node	Jobs	Success Rate	Saved GB	Throughput
Main (NVIDIA)	523	98.7%	250.0	15.3/hr
Secondary (QSV)	412	97.8%	188.3	11.2/hr
Backup (CPU)	312	96.5%	50.0	5.8/hr

Use Cases:

Identify underperforming nodes
Compare GPU vs CPU efficiency
Plan hardware acceleration upgrades

Health Checks

The system continuously monitors (see health check):

Check	Healthy	Warning	Critical
CPU Load	under 1.5x cores	1.5 to 2.0x cores	over 2.0x cores
Memory	under 85%	85-95%	over 95%
Database	Connected	-	Disconnected
Queue	0 stuck jobs	1-5 stuck	over 5 stuck
Nodes	All online	1+ offline	Main offline

Overall Status: Aggregated from all health checks. Dashboard displays: - HEALTHY (green): All checks passing - WARNING (yellow): One or more warnings - CRITICAL (red): One or more critical failures

Troubleshooting Dashboard Issues

No Active Jobs Showing

Possible causes:

No jobs in ENCODING stage (check queue status)
All nodes offline (check node status panel)
Dashboard data not refreshing (refresh browser)

Solution:

# Check queue status via API
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" http://localhost:3100/queue/stats

# Verify nodes are online
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" http://localhost:3100/insights/nodes

Incorrect Storage Stats

Possible causes:

Library paths not configured in database
NFS mounts not accessible
Permission issues reading disk stats

Solution:

# Verify library paths
curl http://localhost:3100/libraries

# Test disk access
df -h /mnt/media/*

Stuck Progress Bars

Possible causes:

Job actually stalled (no FFmpeg progress updates)
WebSocket connection lost (no real-time updates)
Node crashed mid-encode

Solution:

Check backend logs for FFmpeg errors
Refresh dashboard to reconnect WebSocket
Verify node is still online in node status panel

API Endpoints

Access dashboard data programmatically:

Endpoint	Data
`GET /system/dashboard`	Complete dashboard (all panels)
`GET /system/dashboard/health`	Health checks only
`GET /queue/stats`	Queue statistics
`GET /jobs`	All encoding jobs
`GET /jobs/:id`	Single job details
`GET /insights/stats`	Aggregated encoding stats
`GET /insights/savings?days=30`	30-day savings trend
`GET /insights/nodes`	Node performance comparison

Get your JWT token from the browser’s developer tools (F12 → Application → Local Storage → token) or from the login API response. Example: Get dashboard JSON:

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:3100/system/dashboard

Understanding Jobs

Job lifecycle, statuses, and auto-healing

Troubleshooting

Fix stuck jobs, disk space, and node issues

Multi-Node Setup

Track distributed encoding performance

GPU Acceleration

Speed up encoding with hardware acceleration

​Dashboard Overview

System Health

Active Jobs

Queue Status

Performance

​Active Jobs Panel

​Job Information Display

​Progress Indicators

​Node Assignment

​Queue Status

​Pending Jobs

​Estimated Completion Time

​System Stats

​CPU Usage

​Memory Usage

​Disk Space

​Node Status

​Health Indicators

​Active Jobs Per Node

​Load Distribution

​Job History

​Completed Jobs (Last 30 Days)

​Failed Jobs

​Performance Metrics

​Average Encode Speed (fps)

​Storage Saved

​Total Encoding Time

​Advanced Monitoring

​Codec Distribution

​Savings Trend (30-Day)

​Node Performance Comparison

​Health Checks

​Troubleshooting Dashboard Issues

​No Active Jobs Showing

​Incorrect Storage Stats

​Stuck Progress Bars

​API Endpoints

​Related Guides

Understanding Jobs

Troubleshooting

Multi-Node Setup

GPU Acceleration

Dashboard Overview

Active Jobs Panel

Job Information Display

Progress Indicators

Node Assignment

Queue Status

Pending Jobs

Estimated Completion Time

System Stats

CPU Usage

Memory Usage

Disk Space

Node Status

Health Indicators

Active Jobs Per Node

Load Distribution

Job History

Completed Jobs (Last 30 Days)

Failed Jobs

Performance Metrics

Average Encode Speed (fps)

Storage Saved

Total Encoding Time

Advanced Monitoring

Codec Distribution

Savings Trend (30-Day)

Node Performance Comparison

Health Checks

Troubleshooting Dashboard Issues

No Active Jobs Showing

Incorrect Storage Stats

Stuck Progress Bars

API Endpoints

Related Guides