VnStat: Option for VnStat to return structured data from the API requests

[42daha]

I am on a metered internet connection and would like to use the vnstat plugin to help me manage my monthly data usage. My hope is to set up a cron job on a system that would periodically call the vnstat monthly and/or daily APIs, and the cron job could notify me if my usage trend looks like it may be too high for the month.

Ideally, the returning json would be structured with an array of months or days and their corresponding data usage fields as bytes instead of a string designed for console screen output. Could the hourly/daily/monthly/yearly APIs take an optional parameter that would direct them to return an array of structure values instead of the console output string? The current response from api/vnstat/service/monthly looks like:
{"response":"\\n em0 \\/ monthly\\n\\n month rx | tx | total | avg. rate\\n ------------------------+-------------+-------------+---------------\\n Nov \'24 129.66 GiB | 28.63 GiB | 158.29 GiB | 524.58 kbit\\/s\\n Dec \'24 945.11 GiB | 149.33 GiB | 1.07 TiB | 3.76 Mbit\\/s\\n ------------------------+-------------+-------------+---------------\\n estimated 0.99 TiB | 159.80 GiB | 1.14 TiB |\\n\\n\\n"}

Using an optional parameter to request structured data, the response could instead be something like:

{ "response" : [
      { "year" : 2024, "month" : 11, "rx" : 139221364900, "tx" : 30741228421, "avg. rate" : "524.48 kbit\/s" },
      { "year" : 2024, "month" : 12, "rx" : 1014804135482, "tx" : 160341866578, "avg. rate" : 3.76 Mbit\/s" }
   ]
}

The "daily" API call could include "day" as a field in each array element, and the "hourly" API call could also include "hour" as a 24-hour integer. Alternatively, instead of year/month/day/hour fields, a "datetime" field could be populated for all four APIs with the epoch time of the starting second of the interval unit (e.g. "datetime" : 1730419200 for 2024-11-01 00:00:00).

With the structured response, the "total" column and the "estimated" summary row could be dropped since the calling code could calculate those if desired.

From what I understand so far, it looks like the vnstat API is currently being directly used for the output in the web UI as-is by wrapping the output in the <pre> tag. Changing the result of the API without an optional parameter would likely impact the UI.

Update: I now understand that the plugin is invoking the vnstat command line tool. There is a "--json" option for invoking it that would return the information that I was hoping to get.

---

opnsense: v24.7.11_2
VnStat: v1.3_1

[OPNsense-bot]

Thank you for creating an issue.
Since the ticket doesn't seem to be using one of our templates, we're marking this issue as low priority until further notice.

For more information about the policies for this repository,
please read https://github.com/opnsense/plugins/blob/master/CONTRIBUTING.md for further details.

The easiest option to gain traction is to close this ticket and open a new one using one of our templates.

[vergoh]

If you have access to the vnstat cli command and its version is 2.9 or later then an alternative could be to use vnStat's limit alerts feature with the --alert parameter. That way you can skip all the parsing and start actions depending on the command's return value which will be based on the limits you've defined.