Note

From version 0.4 disk and memory measurements include decimals. You can decide which units to use. If you're using number in Homepage's services.yaml values will still show as whole numbers, if you wish to display decimals you can change number to float. Percentages will also include more decimal places, all rounding logic has been removed from the API, and the raw floats will be returned. Homepage's format: percent will format percentages appropriately.

Unraid Simple Monitoring API

Simple REST API to monitor basic metrics, currently supports:

• Disk utilization and status
• Network traffic
• CPU load and temperature
• Memory utilization

Originally created for Unraid for use with Homepage.

Table of Contents

• Utilization with Unraid
  • Installation
  • Configuration
    • Additional pools
    • Custom units
    • CPU Temperature
    • Logging
    • CORS
  • ZFS
  • Calling the API
• Integration with Homepage
  • Configuration
    • Available Fields
• How reliable are the measurements?
• Installing a QA build

Utilization with Unraid

Installation

Unraid Community App

Install from the Unraid community apps.

Manually

Install manually using docker compose.

services:
  unraid-simple-monitoring-api:
    image: ghcr.io/nebn/unraid-simple-monitoring-api:latest
    container_name: unraid-simple-monitoring-api
    privileged: false
    restart: unless-stopped
    ports:
      - '24940:24940'
    volumes:
      - /mnt/user/appdata/unraid-simple-monitoring-api:/app
      - /:/hostfs
    environment:
      - CONF_PATH=/app/conf.yml
      - HOSTFS_PREFIX=/hostfs

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

Additional pools

You can add any number of custom disk pools.

disks:
  poolname:
    - /mnt/pooldisk1
    - /mnt/pooldisk2
  anotherpool:
    - /mnt/anotherdisk

Custom units

You can choose which units the measuresments should use. Accepted values are B (bytes),Ki (KibiBytes),K (KiloBytes) up to Qi and Q. If no unit is specified, a default value will be used.

units:
  array: Ti # Default Gi
  cache: Gi # Default Gi
  pools: Ti # Default Gi
  memory: M # Default Mi

Tip

Use float in your homepage configuration if you wish to see decimals for bigger units, number will round down to the nearest integer.

CPU Temperature file

You can specify which file to read to obtain the correct CPU temperature.

cpuTemp: /path/to/temp/file

To see where this information might be, you can try running the following command:

for dir in /sys/class/hwmon/hwmon*; do
  echo "Directory: $dir"
  for file in $dir/temp*_input; do
    echo "Reading from: $file"
    cat $file
  done
done

If no file is specified in the configuration, the software will attempt to figure it out by running a very quick stress test (a few seconds) while monitoring plausible files. You can find the result of this search in the application's logs. This method is of questionable reliability, specifying which file should be read is the preferred option.

Logging level

loggingLevel: DEBUG

Accepted values are DEBUG INFO WARN and ERROR, it defaults to INFO.

CORS

You can specify these CORS headers:

• Access-Control-Allow-Origin
• Access-Control-Allow-Methods
• Access-Control-Allow-Headers

cors:
  origin: "*"
  methods: "method, method"
  headers: "header-name, header-name"

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. The command zfs list is being used to obtain the correct information, as conventional disk reading methods do not seem to work.

If you are comfortable with running the container as privileged, follow these steps:

• Unraid Docker Tab
• unraid-simple-monitoring-api > Edit
• Change Privileged: to ON
• 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

Click to view an example JSON response

{
  "array": [
    {
      "mount": "/mnt/disk1",
      "total": 3724.20388412476,
      "used": 3608.56298828125,
      "free": 115.640895843506,
      "used_percent": 96.8948827872596,
      "free_percent": 3.10511721274044,
      "temp": 0,
      "disk_id": "WDC_WD40EFPX-1234",
      "is_spinning": false
    },
    {
      "mount": "/mnt/disk2",
      "total": 3724.20388412476,
      "used": 3598.42082977295,
      "free": 125.783054351807,
      "used_percent": 96.6225518724153,
      "free_percent": 3.37744812758466,
      "temp": 0,
      "disk_id": "WDC_WD40EFPX-4321",
      "is_spinning": false
    },
    {
      "mount": "/mnt/disk5",
      "total": 2793.15542221069,
      "used": 2692.77926635742,
      "free": 100.376155853271,
      "used_percent": 96.4063526485101,
      "free_percent": 3.59364735148991,
      "temp": 0,
      "disk_id": "WDC_WD30EFRX-1243",
      "is_spinning": false
    },
    {
      "mount": "/mnt/disk6",
      "total": 1862.10697937012,
      "used": 1749.14831924438,
      "free": 112.958660125732,
      "used_percent": 93.9338254258656,
      "free_percent": 6.06617457413442,
      "temp": 0,
      "disk_id": "WDC_WD2003FZEX-3421",
      "is_spinning": false
    },
    {
      "mount": "/mnt/disk7",
      "total": 931.057510375977,
      "used": 702.875312805176,
      "free": 228.182197570801,
      "used_percent": 75.4921479040906,
      "free_percent": 24.5078520959094,
      "temp": 0,
      "disk_id": "Hitachi_4312",
      "is_spinning": false
    }
  ],
  "cache": [
    {
      "mount": "/mnt/cache",
      "total": 931.512413024902,
      "used": 204.731128692627,
      "free": 726.781284332275,
      "used_percent": 21.978357543063,
      "free_percent": 78.021642456937,
      "temp": 0,
      "disk_id": "Samsung_SSD_870_EVO_1TB_2341",
      "is_spinning": false
    }
  ],
  "pools": [],
  "parity": [
    {
      "name": "parity",
      "temp": 0,
      "disk_id": "WDC_WD80EDBZ-3241",
      "is_spinning": false
    },
    {
      "name": "parity2",
      "temp": 0,
      "disk_id": "",
      "is_spinning": true
    }
  ],
  "network": [
    {
      "interface": "docker0",
      "rx_MiBs": 0,
      "tx_MiBs": 0,
      "rx_Mbps": 0,
      "tx_Mbps": 0
    },
    {
      "interface": "eth0",
      "rx_MiBs": 0.240369570881588,
      "tx_MiBs": 0.00792626055173589,
      "rx_Mbps": 2.01636610525386,
      "tx_Mbps": 0.0664902926743761
    }
  ],
  "array_total": {
    "mount": "/mnt/disk*",
    "total": 13034.7276802063,
    "used": 12351.7867164612,
    "free": 682.940963745117,
    "used_percent": 94.760604283416,
    "free_percent": 5.239395716584,
    "temp": 0,
    "disk_id": "WDC_WD40EFPX-1234 WDC_WD40EFPX-4321 WDC_WD30EFRX-1243 WDC_WD2003FZEX-3421 Hitachi_4312",
    "is_spinning": false
  },
  "cache_total": {
    "mount": "/mnt/cache*",
    "total": 931.512413024902,
    "used": 204.731128692627,
    "free": 726.781284332275,
    "used_percent": 21.978357543063,
    "free_percent": 78.021642456937,
    "temp": 0,
    "disk_id": "Samsung_SSD_870_EVO_1TB_2341",
    "is_spinning": false
  },
  "network_total": {
    "interface": "docker0 eth0",
    "rx_MiBs": 0.240369570881588,
    "tx_MiBs": 0.00792626055173589,
    "rx_Mbps": 2.01636610525386,
    "tx_Mbps": 0.0664902926743761
  },
  "cpu": {
    "load_percent": 9.95962314939435,
    "temp": 33
  },
  "cores": [
    {
      "name": "cpu0",
      "load_percent": 9.15208613728129
    },
    {
      "name": "cpu1",
      "load_percent": 13.1081081081081
    },
    {
      "name": "cpu2",
      "load_percent": 7.93010752688172
    },
    {
      "name": "cpu3",
      "load_percent": 9.79865771812081
    }
  ],
  "memory": {
    "total": 15785.82421875,
    "used": 1387.29296875,
    "free": 14398.53125,
    "used_percent": 8.78822004809992,
    "free_percent": 91.2117799519001
  },
  "error": null
}

Integration with Homepage

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

Available fields

Array Total

- field:
    array_total: free # or used, total, used_percent, free_percent, temp, mount, disk_id, is_spinning
  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, temp, mount, disk_id, is_spinning
  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

Custom pool

- field:
    pools:
      0:
        total: free
      # '0' is the index of the pool, 0 = the first 
      # 'free' is the field you wish to read
  label: your label
  format: number
  suffix: GiB

Specific disk in custom pool

- field:
    pools:
      0: # '0' is the index of the pool, 0 = the first 
        disks: # reading 'disks' list
          0: free # '0' is the index of the disk in the list
  label: your label
  format: number
  suffix: GiB

Parity

- field:
    parity: 
      0: temp 
      # '0' is the index of the parity disk, 0 = the first 
      # 'temp' is the field you wish to read
  label: your label
  format: number
  suffix: °

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 # or temp
  label: your label
  format: percent # or number

Cores

- field:
    cores:
      0: load_percent
  label: cpu0
  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, there are two solutions:

• you can set the widget property display: list to have the fields displayed in a vertical list that can be arbitrarily long

widget:
  type: customapi
  url: http://<unraid-ip>:24940
  display: list
  mappings:
     ...

• instead of widget you can use widgets and specify a list of widgets, each one is able to display up to 4 fields

widgets:
  - type: customapi
    url: http://<unraid-ip>:24940
    method: GET
      mappings:   
        ...

  - type: customapi
    url: http://<unraid-ip>:24940
    method: GET
      mappings:   
        ...

You can also combine the two:

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.

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: to ghcr.io/nebn/unraid-simple-monitoring-api:qa (The actual tag might change, currently using qa)
• 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.

Warning

It is a good idea to switch back to the official build as soon as whatever fix you were testing is deployed to it. QA builds are unstable and are likely to not work correctly if you update them further.