README
¶
Unraid Simple Monitoring API
Simple rest API to monitor basic metrics, currently supports:
- Disk utilization
- Network traffic
- CPU load
- Memory utilization
Originally created for Unraid for use with Homepage.
[!IMPORTANT] Migrated from DockerHub to GitHub Container Registry.
If you have installed before April 2024 please reinstall or manually change
Repositoryto
ghcr.io/nebn/unraid-simple-monitoring-api:latest
And optionally
Registry URLto
https://github.com/NebN/unraid-simple-monitoring-api/pkgs/container/unraid-simple-monitoring-api
I will keep pushing to DockerHub for now, but would like to definitively migrate.
Table of Contents
- Utilization with Unraid
- Integration with Homepage
- How reliable are the measurements?
- Installing a QA build
Utilization with Unraid
Installation
Install from the Unraid community apps
Configuration
By default the application expects a configuration file in
/mnt/user/appdata/unraid-simple-monitoring-api/conf.yml
You can find an example file here. It should look like this
networks:
- eth0
- anotherNetwork
disks:
cache:
- /mnt/cache
- /another/cache/mount
array:
- /mnt/disk1
- /mnt/disk2
Optionally you can specify the desired level of logging by adding the following line
loggingLevel: DEBUG
Accepted values are DEBUG INFO WARN and ERROR, it defaults to INFO.
ZFS
If any of the mount points listed in the configuration are using ZFS, the application needs to be run as privileged in order to obtain the correct utilization of ZFS datasets. Essentially the command zfs list is being used to obtain the correct information, as conventional disk reading methods do not seem work.
If you are comfortable with running the container as privileged, follow these steps:
- Unraid Docker Tab
unraid-simple-monitoring-api> Edit- Change
Privileged:toON - Apply
You can always decide to turn Privileged: back to OFF.
[!TIP] If you are not using ZFS, there is no reason to run the container as privileged.
Calling the API
Make a request to
http://your-unraid-ip:24940
The response will be formatted this way.
{
"array":[
{
"mount":"/mnt/disk1",
"total":3724,
"used":1864,
"free":1860,
"used_percent":50.05,
"free_percent":49.95
},
{
"mount":"/mnt/disk2",
"total":3724,
"used":1366,
"free":2358,
"used_percent":36.68,
"free_percent":63.32
},
{
"mount":"/mnt/disk5",
"total":2793,
"used":20,
"free":2773,
"used_percent":0.72,
"free_percent":99.28
},
{
"mount":"/mnt/disk6",
"total":1862,
"used":85,
"free":1777,
"used_percent":4.56,
"free_percent":95.44
},
{
"mount":"/mnt/disk7",
"total":931,
"used":7,
"free":924,
"used_percent":0.75,
"free_percent":99.25
}
],
"cache":[
{
"mount":"/mnt/cache",
"total":465,
"used":210,
"free":255,
"used_percent":45.16,
"free_percent":54.84
}
],
"network":[
{
"interface":"docker0",
"rx_MiBs":0,
"tx_MiBs":0,
"rx_Mbps":0,
"tx_Mbps":0
},
{
"interface":"eth0",
"rx_MiBs":0.02,
"tx_MiBs":5.22,
"rx_Mbps":0.13,
"tx_Mbps":43.8
}
],
"array_total":{
"mount":"total",
"total":13034,
"used":3342,
"free":9692,
"used_percent":25.64,
"free_percent":74.36
},
"cache_total":{
"mount":"total",
"total":465,
"used":210,
"free":255,
"used_percent":45.16,
"free_percent":54.84
},
"network_total":{
"interface":"total",
"rx_MiBs":0.02,
"tx_MiBs":5.22,
"rx_Mbps":0.13,
"tx_Mbps":43.8
},
"cpu":{
"load_percent":10.6
},
"memory":{
"total":15788,
"used":1288,
"free":14500,
"used_percent":8.16,
"free_percent":91.84
},
"error":null
}
Integration with Homepage
Configuration
Check out Hompage's official custom API widget documentation.
Your homepage services.yaml should look like this if you want it to look like the above example, showing cache and network data.
- Category:
- Unraid:
icon: unraid.png
href: http://<your-unraid-ip>
widget:
type: customapi
url: http://<your-unraid-ip>:24940
method: GET # this doesn't matter
mappings:
- field:
cache_total: free
label: cache free
format: number
suffix: GiB
- field:
cache_total: free_percent
label: percent
format: percent
- field:
network_total: rx_MiBs
label: rx
format: float
suffix: MiB/s
- field:
network_total: tx_MiBs
label: tx
format: float
suffix: MiB/s
The following are examples for each currently available field.
-
Array Total
- field:
array_total: free # or used, total, used_percent, free_percent
label: your label
format: number # or percentage
suffix: GiB # or nothing in case of percentages, or whatver you prefer
-
Cache Total
- field:
cache_total: free # or used, total, used_percent, free_percent
label: your label
format: number # or percentage
suffix: GiB # or nothing in case of percentages, or whatver you prefer
-
Specific Disk
- field:
array: # or cache
0: free
# '0' is the index of the disk, 0 = the first
# 'free' is the field you wish to read
label: your label
format: number
suffix: GiB
-
Network Total
- field:
network_total: rx_MiBs # or tx_MiBs, rx_Mbps, tx_Mbps
label: your label
format: float # or 'number' to round to the nearest integer
suffix: MiB/s # or Mbps, or whatever you prefer
-
Specific Network
- field:
network:
0: rx_MiBs
# '0' is the index of the network, 0 = the first
# 'rx_MiBs' is the field you wish to read
label: your label
format: float
suffix: MiB/s
-
CPU
- field:
cpu: load_percent
label: your label
format: percent
-
Memory
- field:
memory: used_percent # or free_percent, total, used, free
label: your label
format: percent
[!TIP] If you wish to show more than the usual 4 allowed fields, you can set the widget property
display: listto have the fields displayed in a vertical list that can be arbitrarily long.widget: type: customapi display: list mappings: ...
How reliable are the measurements?
The goal of this API is to be simple, fast, and lightweight.
For these reasons, the measurements provided are not as accurate as they could be.
Disk
Disk utilization is rounded down to the nearest GiB.
Network and CPU
Both Network and CPU usage need to be measured for some time interval. Typically, to get an accurate measurement, you would monitor these for a few seconds before providing a response.
To avoid having to either:
- wait for the measurement to be completed before responding
- continuosly measure them to have a recent measurement ready to respond with
A different approach has been taken: a snapshot of Network and CPU usage is taken every time the API is called, and the response is the average Network and CPU usage between the current and last API call. This ensures that the response is quick and reasonably accurate, without having the process continuously read Network and CPU data even when not required.
Installing a QA build
Everyone's Unraid setup is different, therefore, when implementing a new feature or fixing a bug specific to a certain setup, it might be necessary that the end user (you) install a testing deployment to verify that everything works as expected.
To do so follow these steps:
- Unraid Docker Tab
unraid-simple-monitoring-api> Stop- Add container
- Template >
unraid-simple-monitoring-api - Change the name to something else, e.g.:
unraid-simple-monitoring-api-QA - Change
Repository:toghcr.io/nebn/unraid-simple-monitoring-api:qa(The actual tag might change, currently usingqa) - Apply
You should now have 2 installations on your Docker Tab, and can switch between them by stopping/starting them.
[!NOTE]
Avoid having both active at the same time, as they share the same port and would therefore be unable to start the HTTP service.
Directories