mirror/librenms-librenms
1
0
Fork 0
mirror of https://github.com/librenms/librenms.git synced 2024-10-07 16:52:45 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

api: Added support for retrieving health information and graphs #5399 (#5446)

Browse Source
This commit is contained in:
Neil Lathwood
2017-01-19 10:09:20 +00:00
committed by GitHub
parent 09c396e3fc
commit 6df39b9bbd
3 changed files with 225 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

170
doc/API/API-Docs.md
View File

@@ -12,6 +12,8 @@ source: API/API-Docs.md
- [`del_device`](#api-route-2)
- [`get_device`](#api-route-3)
- [`get_graphs`](#api-route-5)
- [`list_available_health_graphs`](#api-route-list_available_health_graphs)
- [`get_health_graph`](#api-route-get_health_graph)
- [`get_graph_generic_by_hostname`](#api-route-6)
- [`get_port_graphs`](#api-route-7)
- [`get_port_stack`](#api-route-29)
@@ -29,6 +31,8 @@ source: API/API-Docs.md
- [`devicegroups`](#api-devicegroups)
- [`get_devicegroups`](#api-route-get_devicegroups)
- [`get_devices_by_group`](#api-route-get_devices_by_group)
- [`portgroups`](#api-portgroups)
- [`get_graph_by_portgroup`](#api-route-get_graph_by_portgroup)
- [`routing`](#api-routing)
- [`list_bgp`](#api-route-1)
- [`list_ipsec`](#list_ipsec)
@@ -221,6 +225,146 @@ Output:
}
```
### <a name="api-route-list_available_health_graphs">Function: `list_available_health_graphs`</a> [`top`](#top)
This function allows to do three things:
- Get a list of overall health graphs available.
- Get a list of health graphs based on provided class.
- Get the health sensors information based on ID.
Route: /api/v0/devices/:hostname/health(/:type)(/:sensor_id)
- hostname can be either the device hostname or id
- type (optional) is health type / sensor class
- sensor_id (optional) is the sensor id to retreive specific information.
Input:
-
Example:
```curl
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/health
```
Output:
```
{
"status": "ok",
"err-msg": "",
"count": 2,
"graphs": [
{
"desc": "Airflow",
"name": "device_airflow"
},
{
"desc": "Voltage",
"name": "device_voltage"
}
]
}
```
Example:
```curl
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/health/device_voltage
```
Output:
```
{
"status": "ok",
"err-msg": "",
"count": 2,
"graphs": [
{
"sensor_id": "1",
"desc": "Input Feed A"
},
{
"sensor_id": "2",
"desc": "Output Feed"
}
]
}
```
Example:
```curl
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/health/device_voltage/1
```
Output:
```
{
"status": "ok",
"err-msg": "",
"count": 1,
"graphs": [
{
"sensor_id": "1",
"sensor_deleted": "0",
"sensor_class": "voltage",
"device_id": "1",
"poller_type": "snmp",
"sensor_oid": ".1.3.6.1.4.1.318.1.1.27.1.1.0",
"sensor_index": "1",
"sensor_type": "apc",
"sensor_descr": "Input",
"sensor_divisor": "1",
"sensor_multiplier": "1",
"sensor_current": "1",
"sensor_limit": "1.15",
"sensor_limit_warn": null,
"sensor_limit_low": "0.85",
"sensor_limit_low_warn": null,
"sensor_alert": "1",
"sensor_custom": "No",
"entPhysicalIndex": null,
"entPhysicalIndex_measured": null,
"lastupdate": "2017-01-13 13:50:26",
"sensor_prev": "1"
}
]
}
```
### <a name="api-route-get_health_graph">Function: `get_health_graph`</a> [`top`](#top)
Get a particular health class graph for a device, if you provide a sensor_id as well then a single sensor graph
will be provided. If no sensor_id value is provided then you will be sent a stacked sensor graph.
Route: /api/v0/devices/:hostname/graphs/health/:type(/:sensor_id)
- hostname can be either the device hostname or id
- type is the name of the health graph as returned by [`list_available_health_graphs`](#api-route-list_available_health_graphs)
- sensor_id (optional) restricts the graph to return a particular health sensor graph.
Input:
-
Example:
```curl
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/graphs/health/device_voltage
```
Output:
Output is a stacked graph for the health type provided.
Example:
```curl
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/graphs/health/device_voltage/1
```
Output:
Output is the graph of the particular health type sensor provided.
### <a name="api-route-6">Function: `get_graph_generic_by_hostname`</a> [`top`](#top)
Get a specific graph for a device, this does not include ports.
@@ -823,6 +967,32 @@ Output:
]
```
## <a name="api-portgroups">`Port Groups`</a> [`top`](#top)
### <a name="api-route-get_graph_by_portgroup">Function: `get_graph_by_portgroup`</a> [`top`](#top)
Get the graph based on the group type.
Route: /api/v0/devices/portgroups/:group
- group is the type of port group graph you want, I.e Transit, Peering, etc. You can specify multiple types comma separated.
Input:
- from: This is the date you would like the graph to start - See http://oss.oetiker.ch/rrdtool/doc/rrdgraph.en.html for more information.
- to: This is the date you would like the graph to end - See http://oss.oetiker.ch/rrdtool/doc/rrdgraph.en.html for more information.
- width: The graph width, defaults to 1075.
- height: The graph height, defaults to 300.
Example:
```curl
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/portgroups/transit,peering
```
Output:
Output is an image.
## <a name="api-routing">`Routing`</a> [`top`](#top)
### <a name="api-route-1">Function: `list_bgp`</a> [`top`](#top)

3
html/api_v0.php
View File

@@ -40,6 +40,8 @@ $app->group(
// api/v0/devices/$hostname/vlans
$app->get('/:hostname/graphs', 'authToken', 'get_graphs')->name('get_graphs');
// api/v0/devices/$hostname/graphs
$app->get('/:hostname/health(/:type)(/:sensor_id)', 'authToken', 'list_available_health_graphs')->name('list_available_health_graphs');
// api/v0/devices/$hostname/health
$app->get('/:hostname/ports', 'authToken', 'get_port_graphs')->name('get_port_graphs');
$app->get('/:hostname/port_stack', 'authToken', 'get_port_stack')->name('get_port_stack');
// api/v0/devices/$hostname/ports
@@ -48,6 +50,7 @@ $app->group(
$app->put('/:hostname/components', 'authToken', 'edit_components')->name('edit_components');
$app->delete('/:hostname/components/:component', 'authToken', 'delete_components')->name('delete_components');
$app->get('/:hostname/groups', 'authToken', 'get_device_groups')->name('get_device_groups');
$app->get('/:hostname/graphs/health/:type(/:sensor_id)', 'authToken', 'get_graph_generic_by_hostname')->name('get_health_graph');
$app->get('/:hostname/:type', 'authToken', 'get_graph_generic_by_hostname')->name('get_graph_generic_by_hostname');
// api/v0/devices/$hostname/$type
$app->get('/:hostname/ports/:ifname', 'authToken', 'get_port_stats_by_port_hostname')->name('get_port_stats_by_port_hostname');

52
html/includes/api_functions.inc.php
View File

@@ -123,8 +123,13 @@ function get_graph_generic_by_hostname()
$app = \Slim\Slim::getInstance();
$router = $app->router()->getCurrentRoute()->getParams();
$hostname = $router['hostname'];
$sensor_id = $router['sensor_id'] ?: null;
$vars = array();
$vars['type'] = $router['type'] ?: 'device_uptime';
if (isset($sensor_id)) {
$vars['id'] = $sensor_id;
$vars['type'] = str_replace('device_', 'sensor_', $vars['type']);
}
// use hostname as device_id if it's all digits
$device_id = ctype_digit($hostname) ? $hostname : getidbyname($hostname);
@@ -678,6 +683,53 @@ function get_graphs()
echo _json_encode($output);
}
function list_available_health_graphs()
{
global $config;
$code = 200;
$status = 'ok';
$message = '';
$app = \Slim\Slim::getInstance();
$router = $app->router()->getCurrentRoute()->getParams();
$hostname = $router['hostname'];
$device_id = ctype_digit($hostname) ? $hostname : getidbyname($hostname);
if (isset($router['type'])) {
list($dump, $type) = explode('_', $router['type']);
}
$sensor_id = $router['sensor_id'] ?: null;
$graphs = array();
if (isset($type)) {
if (isset($sensor_id)) {
$graphs = dbFetchRows('SELECT * FROM `sensors` WHERE `sensor_id` = ?', array($sensor_id));
} else {
foreach (dbFetchRows('SELECT `sensor_id`, `sensor_descr` FROM `sensors` WHERE `device_id` = ? AND `sensor_class` = ? AND `sensor_deleted` = 0', array($device_id, $type)) as $graph) {
$graphs[] = array(
'sensor_id' => $graph['sensor_id'],
'desc' => $graph['sensor_descr'],
);
}
}
} else {
foreach (dbFetchRows('SELECT `sensor_class` FROM `sensors` WHERE `device_id` = ? AND `sensor_deleted` = 0 GROUP BY `sensor_class`', array($device_id)) as $graph) {
$graphs[] = array(
'desc' => ucfirst($graph['sensor_class']),
'name' => 'device_'.$graph['sensor_class'],
);
}
}
$total_graphs = count($graphs);
$output = array(
'status' => "$status",
'err-msg' => $message,
'count' => $total_graphs,
'graphs' => $graphs,
);
$app->response->setStatus($code);
$app->response->headers->set('Content-Type', 'application/json');
echo _json_encode($output);
}
function get_port_graphs()
{