mirror of
https://github.com/librenms/librenms.git
synced 2024-10-07 16:52:45 +00:00
a166df006a
* add lnms_return_optimizer * add compression test using zfs-v1 * minor style fix * save the original output if not json * replace gzinflate with gzdecode as apparently that does not require yanking the header * Minor comment cleanup. Also note it in the application notes as well. * update docs on how it is called * update the spelling of it in a few places * and a few more * dev docs updated a bit * the suricata extend has native support for this now * add exception handling for base64 and gzip decoding failure * minor cleanup for new exceptions * minor misc changes * minor formatting fix * more phpdoc tweaks * minor formatting tweak * remember to actually include the new exceptions * more phpdoc tweaking * correct name in JsonAppGzipDecodeException * add debug and verbose output * style fix * not base64 is it starts with a line with only a integer
92 lines
2.9 KiB
Markdown
92 lines
2.9 KiB
Markdown
# 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`...
|
|
|
|
```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);
|
|
```
|