> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitbonsai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Dashboard & Monitoring

> Real-time system monitoring and job tracking

The BitBonsai dashboard provides comprehensive system monitoring, [job](/glossary#job) tracking, and performance analytics in a single unified view.

<Info>
  **What is the dashboard?** The main screen showing all your [encoding](/glossary#encoding)
  activity, [queue](/glossary#queue) status, and system health in real-time.
</Info>

## 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.

<CardGroup cols={2}>
  <Card title="System Health" icon="heartbeat">
    CPU, memory, and database status checks
  </Card>

  <Card title="Active Jobs" icon="play">
    Real-time encoding progress tracking
  </Card>

  <Card title="Queue Status" icon="list">
    Pending jobs and estimated completion
  </Card>

  <Card title="Performance" icon="chart-line">
    Throughput, savings, and efficiency metrics
  </Card>
</CardGroup>

## Active Jobs Panel

Shows [encoding](/glossary#encoding) tasks currently being processed across all [nodes](/glossary#node).

### 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](/glossary#node) is processing this [job](/glossary#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](/glossary#job) shows which [node](/glossary#node) is processing it. This helps identify:

* [Load distribution](/glossary#load-balancing) across nodes
* Node performance differences ([GPU](/glossary#gpu) vs CPU)
* Potential bottlenecks (one node handling too many jobs)

## Queue Status

### Pending Jobs

Shows [jobs](/glossary#job) waiting to be processed:

| Metric        | Meaning                                                                                            |
| ------------- | -------------------------------------------------------------------------------------------------- |
| **QUEUED**    | Jobs waiting for available [node](/glossary#node) capacity                                         |
| **PENDING**   | Jobs discovered but not yet [queued](/glossary#queue) (awaiting [library](/glossary#library) scan) |
| **ANALYZING** | Files being analyzed for [codec](/glossary#codec)/[bitrate](/glossary#bitrate) information         |

### Estimated Completion Time

Calculated based on:

1. **Current throughput**: Average jobs completed per hour (last 24h)
2. **Queue depth**: Total jobs in `QUEUED` and `ANALYZING` stages
3. **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](/glossary#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%    |

<Warning>
  **Low Disk Space**: When any path exceeds 90% usage, [encoding](/glossary#encoding) may fail if
  output file cannot be written. BitBonsai needs temporary space (see [temporary
  files](/glossary#temporary-files)).
</Warning>

## Node Status

### Health Indicators

Each [node](/glossary#node) displays a status badge:

* **🟢 ONLINE**: Node is healthy and accepting [jobs](/glossary#job)
* **🔴 OFFLINE**: Node unreachable or not responding to [health checks](/glossary#health-check)
* **🟡 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](/glossary#job) are distributed across [nodes](/glossary#node):

* **[Main node](/glossary#main-node)**: Primary [encoding](/glossary#encoding) node (usually [GPU](/glossary#gpu)-accelerated)
* **[Child nodes](/glossary#child-node)**: 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](/glossary#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](/glossary#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](/glossary#codec) (20%)
* **[FFmpeg](/glossary#ffmpeg) Errors**: Encoding process crashed (10%)
* **Other**: Miscellaneous errors (5%)

<Info>
  **[Auto-Retry](/glossary#self-healing)**: Failed [jobs](/glossary#job) are automatically retried
  up to 3 times with different encoding settings before being marked as permanently failed.
</Info>

## Performance Metrics

### Average Encode Speed (fps)

Frames per second processed by the [encoding](/glossary#encoding) engine:

| Hardware                                         | Typical Speed | Use Case                             |
| ------------------------------------------------ | ------------- | ------------------------------------ |
| **NVIDIA [GPU](/glossary#gpu)**                  | 40-80 fps     | [HEVC](/glossary#codec)/AV1 encoding |
| **Intel [QSV](/glossary#hardware-acceleration)** | 20-40 fps     | HEVC encoding                        |
| **AMD GPU**                                      | 25-50 fps     | HEVC encoding                        |
| **CPU-only**                                     | 3-8 fps       | Fallback for unsupported hardware    |

**Factors Affecting Speed:**

1. **[Resolution](/glossary#resolution)**: 4K files encode slower than 1080p (\~60% speed reduction)
2. **[Codec](/glossary#codec)**: AV1 is \~40% slower than HEVC, HEVC is \~30% slower than H.264
3. **[Bitrate](/glossary#bitrate)**: Higher bitrate source files take longer to process
4. **Concurrent Jobs**: Multiple [jobs](/glossary#job) share GPU/CPU resources

### Storage Saved

Total space saved by re-[encoding](/glossary#encoding) to [HEVC](/glossary#codec)/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](/glossary#codec) Conversion:**

| From → To                       | Avg Savings | Quality Impact                                 |
| ------------------------------- | ----------- | ---------------------------------------------- |
| H.264 → [HEVC](/glossary#codec) | 40-50%      | Visually identical (same [CRF](/glossary#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](/glossary#codec) usage analytics:

* Pie chart showing H.264, [HEVC](/glossary#codec), AV1, VP9 distribution
* Percentage of [library](/glossary#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](/glossary#encoding) velocity (GB saved per day)

### Node Performance Comparison

Compare [encoding](/glossary#encoding) efficiency across [nodes](/glossary#node):

| Node                                               | Jobs | Success Rate | Saved GB | Throughput |
| -------------------------------------------------- | ---- | ------------ | -------- | ---------- |
| Main (NVIDIA)                                      | 523  | 98.7%        | 250.0    | 15.3/hr    |
| Secondary ([QSV](/glossary#hardware-acceleration)) | 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](/glossary#gpu) vs CPU efficiency
* Plan [hardware acceleration](/glossary#hardware-acceleration) upgrades

## Health Checks

The system continuously monitors (see [health check](/glossary#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](/glossary#database)** | Connected                     | -                 | Disconnected                        |
| **[Queue](/glossary#queue)**       | 0 stuck [jobs](/glossary#job) | 1-5 stuck         | over 5 stuck                        |
| **[Nodes](/glossary#node)**        | All online                    | 1+ offline        | [Main](/glossary#main-node) offline |

<Check>
  **Overall Status**: Aggregated from all [health checks](/glossary#health-check). Dashboard
  displays: - **HEALTHY** (green): All checks passing - **WARNING** (yellow): One or more warnings -
  **CRITICAL** (red): One or more critical failures
</Check>

## Troubleshooting Dashboard Issues

### No Active Jobs Showing

**Possible causes:**

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

**Solution:**

```bash theme={null}
# 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:**

1. [Library](/glossary#library) paths not configured in [database](/glossary#database)
2. [NFS](/glossary#nfs) mounts not accessible
3. Permission issues reading disk stats

**Solution:**

```bash theme={null}
# Verify library paths
curl http://localhost:3100/libraries

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

### Stuck Progress Bars

**Possible causes:**

1. [Job](/glossary#job) actually stalled (no [FFmpeg](/glossary#ffmpeg) progress updates)
2. WebSocket connection lost (no real-time updates)
3. [Node](/glossary#node) crashed mid-[encode](/glossary#encoding)

**Solution:**

1. Check backend logs for FFmpeg errors
2. Refresh dashboard to reconnect WebSocket
3. 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:**

```bash theme={null}
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:3100/system/dashboard
```

## Related Guides

<CardGroup cols={2}>
  <Card title="Understanding Jobs" icon="list-check" href="/guides/understanding-jobs">
    Job lifecycle, statuses, and auto-healing
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/advanced/troubleshooting">
    Fix stuck jobs, disk space, and node issues
  </Card>

  <Card title="Multi-Node Setup" icon="server" href="/advanced/multi-node">
    Track distributed encoding performance
  </Card>

  <Card title="GPU Acceleration" icon="bolt" href="/advanced/gpu-acceleration">
    Speed up encoding with hardware acceleration
  </Card>
</CardGroup>