Device Metrics
Audience: End users and non-technical stakeholders Last Updated: 2026-04-05 Version: 2.0.0
Overview
Llamafin includes a comprehensive device performance monitoring system that tracks your device's health in real-time. Whether you are streaming music, downloading your library, or running audio analysis, the app monitors CPU usage, memory consumption, disk activity, battery level, and network speed.
This system serves two purposes:
- Diagnostics: Helps you understand how Llamafin is performing on your specific device
- Intelligent decisions: The app uses this data to automatically adjust playback quality for the best experience
Key Concepts
1. Metrics Tracked
Llamafin monitors several aspects of your device's performance:
| Metric | What It Measures | Why It Matters |
|---|---|---|
| CPU Usage | How much processing power is being used (system-wide and by Llamafin specifically) | High CPU can cause audio glitches, stuttering, or delays |
| RAM Usage | How much memory is being used (system-wide and by Llamafin) | Low memory can cause the app to slow down or crash |
| Disk Space | Total, used, and free storage on your device | Insufficient space prevents downloads and can cause system instability |
| Disk Activity | How much data is being read from and written to storage | High disk activity can slow down downloads and playback |
| Battery Level | Current battery percentage | Helps the app make energy-conscious decisions |
| JavaScript Heap | Memory used by the app's web code (Chromium browsers only) | Indicates potential memory issues within the app |
| Network Speed | Your actual download speed (measured from image loads) | Determines appropriate streaming quality |
2. Real-Time Monitoring
When you open the Live Metrics page (Settings > Advanced > Debugging > Live Metrics), Llamafin begins collecting metrics every 2 seconds and displays them in real-time charts:
- CPU Usage chart (system vs. app)
- RAM Usage chart (system vs. app)
- JS Heap chart
- Disk I/O chart (read vs. written)
- Battery Level chart
- Network Speed chart
- Visualisation Subscribers chart
The monitoring stops automatically when you leave the page to save battery and processing power.
3. Background Monitoring
Even when you are not viewing the Live Metrics page, Llamafin monitors your device in the background at a low frequency (every 30 seconds) when the app is idle. This serves two purposes:
- Baseline data collection: Builds a picture of your device's typical performance
- LlamaSense decisions: The app uses this data to determine the best playback strategy
When the app is busy (playing music or downloading), background monitoring pauses to save resources.
4. Historical Metrics
All collected metrics are stored and can be viewed on the Historical Metrics page (Settings > Advanced > Debugging > Historical Metrics). Here you can:
- Filter by date range: Select a start and end date to view specific time periods
- Filter by context: Search for specific events (e.g., "storage_check", "LlamaSense")
- View 5 charts: CPU, RAM, JS Heap, Disk I/O, and Network Speed
- Export data: Download your metrics data as JSON, CSV, or text files
5. History Retention
Metrics history is stored up to a configurable limit:
- Default: 10,000 entries
- Adjustable: You can reduce this limit in Settings > Advanced > History Caps
- No time-based expiry: Entries are only removed when the cap is reduced or the maximum is exceeded
6. Storage Warnings
Llamafin monitors your device's free disk space and provides progressive warnings:
| Free Space | Warning Level | Behaviour |
|---|---|---|
| Below 2GB | Information | Info notification shown |
| Below 1GB | Warning | Warning notification shown |
| Below 500MB | Critical | Error notification with "Free Up Space" action (cannot be dismissed) |
These warnings can be enabled or disabled in your notification settings.
7. Storage Verification Before Downloads
Before starting a download, Llamafin checks if your device has enough free space:
- Adds a 500MB safety buffer to prevent system instability
- Respects your download location setting (internal storage vs. external SD card)
- If insufficient space, the download is blocked and you are notified
8. LlamaSense Playback Decisions
LlamaSense is an intelligent decision engine that evaluates your device's current health and network conditions to determine the best playback strategy:
| Condition | Decision | Reason |
|---|---|---|
| CPU above 85% | Transcode to low quality (96kbps) | System is overloaded; reduce processing demands |
| RAM below 200MB free | Transcode to medium quality (128kbps) | Memory is constrained |
| Network below 2 Mbps | Transcode to low quality (96kbps) | Very slow connection |
| Network below 5 Mbps | Transcode to medium quality (128kbps) | Slow connection |
| Otherwise | Direct Play (High Quality) | Device and network can handle it |
This ensures smooth playback even on constrained devices or slow networks.
9. Performance Debugging Toggle
In Settings > Advanced, there is an option to enable performance debugging. When enabled:
- The metrics stream stays ON even when the app is busy
- Useful for developers and advanced users diagnosing performance issues
- When disabled (default), the stream pauses during playback and downloads to save resources
10. Data Export
You can export your device metrics data for analysis:
- JSON format: Full structured data with all fields
- CSV format: Spreadsheet-compatible
- Text/Log format: Human-readable log format
Exports include both device metrics and network speed history.
Configuration
Device Metrics Settings
| Setting | Location | Description |
|---|---|---|
| Metrics History Cap | Settings > Advanced > History Caps | Maximum number of metric entries to store (default: 10,000) |
| Enable Performance Debugging | Settings > Advanced > Debugging | Forces metrics stream to stay ON even during playback/downloads |
| Storage Warnings | Settings > Notifications | Enable/disable progressive disk space warnings |
Live Metrics Page
Access: Settings > Advanced > Debugging > Live Metrics
| Feature | Description |
|---|---|
| 7 real-time charts | CPU, RAM, JS Heap, Disk I/O, Battery, Network, Visualisation Subscribers |
| 2-second update interval | Fresh data every 2 seconds |
| Auto-start/stop | Monitoring starts when you enter the page and stops when you leave |
Historical Metrics Page
Access: Settings > Advanced > Debugging > Historical Metrics
| Feature | Description |
|---|---|
| 5 filtered charts | CPU, RAM, JS Heap, Disk I/O, Network Speed |
| Date range filter | Select start and end dates |
| Context filter | Search for specific events (e.g., "storage_check") |
| Export button | Download metrics as JSON, CSV, or text |
How It Works
Metrics Collection Flow
1. Stream started (manually or by LlamaSense)
↓
2. Timer fires at configured interval (2s live, 30s background)
↓
3. Native plugin collects device metrics:
- CPU usage (system + app)
- RAM usage (system + app)
- Disk space and I/O
- Battery level
↓
4. Web API supplements with JS Heap data
↓
5. Metrics merged into a single snapshot with timestamp
↓
6. Snapshot added to in-memory history (max 10,000 entries)
↓
7. Charts update with new data point
↓
8. History saved to storage (at most every 10 seconds)
Intelligent Stream Management
App continuously monitors:
- Number of active downloads
- Whether audio is playing
- Performance debugging setting
↓
Is app busy? (downloading OR playing)
↓
├── Yes ──→ Performance debugging enabled?
│ │
│ ├── Yes ──→ Stream stays ON
│ └── No ──→ Stream turns OFF (save resources)
│
└── No ──→ Stream turns ON (30s background monitoring)
Storage Check Before Download
1. User initiates a download
↓
2. App triggers fresh metrics load
↓
3. Current free disk space read from device
↓
4. Required space = download size + 500MB safety buffer
↓
5. If free space >= required:
- Download proceeds
↓
6. If free space < required:
- Download blocked
- Error notification shown
- "Free Up Space" action offered
LlamaSense Decision Process
1. User requests playback
↓
2. LlamaSense evaluates current device state:
- CPU usage (from latest metric)
- Free RAM (from latest metric)
- Network speed (from speed history)
↓
3. Rules engine applies:
- CPU > 85%? → Low quality transcode
- RAM < 200MB? → Medium quality transcode
- Network < 2Mbps? → Low quality transcode
- Network < 5Mbps? → Medium quality transcode
- Otherwise? → Direct Play (High Quality)
↓
4. Playback begins with determined strategy
History Persistence
Metrics saved to storage via two mechanisms:
1. Periodic save:
- Every time new metrics arrive
- Debounced to at most once every 10 seconds
- Prevents excessive storage writes during high-frequency streaming
2. On page/tab close:
- beforeunload event triggers immediate save
- Ensures current session's data is not lost
Integration with Other Features
| Feature | Metrics Integration | Description |
|---|---|---|
| Downloads | Storage verification | Fresh metrics before each download to ensure sufficient space |
| Network | Combined in LlamaSense | Device health + network speed = optimal playback decision |
| Audio | Stream management | Playback state determines when to pause/resume monitoring |
| Settings | History cap, debugging toggle | User controls metrics behaviour |
| Sonic Analysis | Device state capture | Current metrics recorded during audio analysis |
| Notifications | Storage warnings | Progressive alerts for low disk space |
| Diagnostics Export | Full history export | JSON/CSV/log export for analysis |
Error Handling & Reliability
Metrics Collection Failures
| Scenario | Behaviour |
|---|---|
| Native plugin unavailable | Error logged, failure toast shown, stream continues (may produce partial data) |
| Web API unavailable (Firefox/Safari) | JS Heap metrics return null; other metrics continue normally |
| Storage write fails | Error logged silently, no user disruption, stream continues |
Storage Check Failures
| Scenario | Behaviour |
|---|---|
| Disk space query fails | Error logged, download may proceed without verification |
| Insufficient space detected | Download blocked, error notification with "Free Up Space" action |
Stream Lifecycle Reliability
| Scenario | Behaviour |
|---|---|
| Multiple pages request stream | Reference counting ensures only one stream runs; stops only when last client leaves |
| Page closes unexpectedly | beforeunload saves current history; stream stops automatically |
| App crashes | Last periodic save (at most 10 seconds ago) preserved |
Technical Specifications
| Specification | Value | Description |
|---|---|---|
| Metrics Categories | 7 | CPU, RAM, Disk Space, Disk I/O, Battery, JS Heap, Network Speed |
| History Cap (Default) | 10,000 entries | Maximum in-memory history |
| Live Chart Display | Last 100 entries | Prevents rendering performance issues |
| Live Stream Interval | 2 seconds | Live Metrics page |
| Default Stream Interval | 3 seconds | Standard polling frequency |
| Background Stream Interval | 30 seconds | Low-frequency idle monitoring |
| History Save Interval | At most every 10 seconds | Debounced persistence |
| Storage Safety Buffer | 500MB | Added to required download space |
| Storage Warning Thresholds | < 2GB, < 1GB, < 500MB | Progressive warning levels |
| LlamaSense CPU Threshold | 85% | Above this, transcode to low quality |
| LlamaSense RAM Threshold | 200MB free | Below this, transcode to medium quality |
| LlamaSense Network Thresholds | < 2Mbps, < 5Mbps | Below these, transcode to lower quality |
| Export Formats | JSON, CSV, Text (log) | Diagnostics export options |
| Plugin | llamafin-device-metrics | Custom Capacitor plugin |
Known Limitations
Metrics Coverage
- No device temperature: Temperature is not tracked, so thermal throttling cannot be monitored
- Battery details limited: Only battery percentage is tracked; charging state and health are not available
- No FPS tracking: Frame rate is tracked by a separate debugging feature, not integrated into metrics charts
- No memory leak detection: Only current heap size is tracked, not trend analysis over time
Platform Coverage
- JS Heap: Only available in Chromium-based browsers (Chrome, Edge, Android WebView). Unavailable on Firefox, Safari, and iOS WebView.
- Native plugin metrics: Availability may vary by platform (iOS vs. Android vs. Web vs. Electron)
History Management
- No time-based expiry: Entries are only removed when the cap is manually reduced or the 10,000 entry maximum is exceeded. Old entries can persist indefinitely.
- No automatic cleanup: The app does not automatically prune old entries based on age.
Related Documentation
- Network Management -- Network speed measurement and history
- Settings System -- Advanced settings for metrics configuration
- Downloads System -- Storage verification before downloads
- Sonic Analysis -- Device state during audio analysis