Notes On Application Development
LibreNMS JSON SNMP Extends
The polling function json_app_get
makes it easy to poll complex data using SNMP extends and JSON.
The following exceptions are provided by it.
It takes three parameters, in order in the list below.
- Integer :: Device ID to fetch it for.
- String :: The extend name. For example, if 'zfs' is passed it will be converted to 'nsExtendOutputFull.3.122.102.115'.
- Integer :: Minimum expected version of the JSON return.
The required keys for the returned JSON are as below.
- version :: The version of the snmp extend script. Should be numeric and at least 1.
- error :: Error code from the snmp extend script. Should be > 0 (0 will be ignored and negatives are reserved)
- errorString :: Text to describe the error.
- data :: An key with an array with the data to be used.
The supported exceptions are as below.
- JsonAppPollingFailedException :: Empty return from SNMP.
- JsonAppParsingFailedException :: Could not parse the JSON
- JsonAppBlankJsonException :: Blank JSON.
- JsonAppMissingKeysException :: Missing required keys.
- JsonAppWrongVersionException :: Older version than supported.
- JsonAppExtendErroredException :: Polling and parsing was good, but the returned data has an error set. This may be checked via $e->getParsedJson() and then checking the keys error and errorString.
The error value can be accessed via $e->getCode(). The output can be accessed via $->getOutput() Only returned JsonAppParsingFailedException. The parsed JSON can be access via $e->getParsedJson().
An example below from includes/polling/applications/zfs.inc.php
...
try {
$zfs = json_app_get($device, $name, 1)['data'];
} catch (JsonAppMissingKeysException $e) {
//old version with out the data key
$zfs = $e->getParsedJson();
} catch (JsonAppException $e) {
echo PHP_EOL . $name . ':' . $e->getCode() . ':' . $e->getMessage() . PHP_EOL;
update_application($app, $e->getCode() . ':' . $e->getMessage(), []);
return;
}
Compression
Also worth noting that json_app_get
supports compressed data via base64 encoded gzip. If base64 encoding is detected on the the SNMP return, it will be gunzipped and then parsed.
https://github.com/librenms/librenms-agent/blob/master/utils/librenms_return_optimizer
may be used to optimize JSON returns.
Application Data Storage
The $app
model is supplied for each application poller and graph. You may access and update the $app->data
field to store arrays of data the Application model.
When you call update_application() the $app
model will be saved along with any changes to the data field.
// set the varaible data to $foo
$app->data = [
'item_A' => 123,
'item_B' => 4.5,
'type' => 'foo',
'other_items' => [ 'a', 'b', 'c' ],
];
// save the change
$app->save();
// var_dump the contents of the variable
var_dump($app->data);