mirror of
https://github.com/librenms/librenms.git
synced 2024-09-21 18:38:25 +00:00
assorted cleanups to alerting docs, primarily to make mdl happier (#13950)
* make mdl more happy for transports.md * more tweaks for the splunk bits * minor fix to entities.md * try that again... * ... * okay, just leave that as is * minor fixes to templates.md * remote some trailling spaces * wrap a line macros.md * cleanup Rules.md reworked the videos section a bit to be more formatting consistent, I hope * header cleanup for testing.md * transports.md cleanup part 2
This commit is contained in:
Zane C. Bowers-Hadley
GitHub
parent
72aa258c43
commit
1bdcd8fad2
@ -47,7 +47,7 @@ Entity | Description
|
||||
## Memory pools
|
||||
|
||||
Entity | Description
|
||||
---|---
|
||||
|---|---|
|
||||
`mempools.mempool_type` | The memory pool type such as hrstorage, cmp and cemp
|
||||
`mempools.mempool_descr` | The description of the pool such as Physical memory, Virtual memory and System memory
|
||||
`mempools.mempool_perc` | The used percentage of the memory pool.
|
||||
|
||||
@ -83,7 +83,9 @@ Entity: `macros.port_usage_perc`
|
||||
|
||||
Description: Return port-usage (max value of in and out) in percent.
|
||||
|
||||
Source: `((SELECT IF(ports.ifOutOctets_rate>ports.ifInOctets_rate, ports.ifOutOctets_rate, ports.ifInOctets_rate)*8) / ports.ifSpeed)*100`
|
||||
Source: `((SELECT IF(ports.ifOutOctets_rate>ports.ifInOctets_rate,
|
||||
ports.ifOutOctets_rate, ports.ifInOctets_rate)*8) /
|
||||
ports.ifSpeed)*100`
|
||||
|
||||
## Time
|
||||
|
||||
|
||||
@ -7,13 +7,13 @@ The GUI provides a simple way of creating rules.
|
||||
Creating more complicated rules which may include maths calculations
|
||||
and MySQL queries can be done using [macros](Macros.md)
|
||||
|
||||
#### Video on how the alert rules work in LibreNMS
|
||||
## Example Videos
|
||||
|
||||
[Alert Rules](https://youtu.be/ryv0j8GEkhM)
|
||||
Video on how the alert rules work in LibreNMS using [Alert
|
||||
Rules](https://youtu.be/ryv0j8GEkhM)
|
||||
|
||||
#### Video on how to use alert rule with wildcards
|
||||
|
||||
[Alert Rules wildcard](https://youtu.be/eYYioFNcrAk)
|
||||
Video on how to use alert rule with [Alert Rules
|
||||
wildcard](https://youtu.be/eYYioFNcrAk)
|
||||
|
||||
## Syntax
|
||||
|
||||
@ -80,7 +80,11 @@ On the Advanced tab, you can specify some additional options for the alert rule:
|
||||
- An example of this would be an average rule for all CPUs over 10%
|
||||
|
||||
```sql
|
||||
SELECT *,AVG(processors.processor_usage) as cpu_avg FROM devices,processors WHERE (devices.device_id = ? AND devices.device_id = processors.device_id) AND (devices.status = 1 && (devices.disabled = 0 && devices.ignore = 0)) = 1 HAVING AVG(processors.processor_usage) > 10
|
||||
SELECT *,AVG(processors.processor_usage) as cpu_avg FROM
|
||||
devices,processors WHERE (devices.device_id = ? AND devices.device_id
|
||||
= processors.device_id) AND (devices.status = 1 && (devices.disabled =
|
||||
0 && devices.ignore = 0)) = 1 HAVING AVG(processors.processor_usage)
|
||||
> 10
|
||||
```
|
||||
|
||||
> The 10 would then contain the average CPU usage value, you can
|
||||
|
||||
@ -141,7 +141,7 @@ More info: [https://laravel.com/docs/blade#extending-a-layout](https://laravel.c
|
||||
|
||||
## Examples
|
||||
|
||||
#### Default Template
|
||||
### Default Template
|
||||
|
||||
```text
|
||||
{{ $alert->title }}
|
||||
@ -295,7 +295,14 @@ $config['allow_unauth_graphs'] = true;
|
||||
|
||||
## Using models for optional data
|
||||
|
||||
If some value does not exist withing the `$faults[]`-array, you may query fields from the database using Laravel models. You may use models to query additional values and use them on the template by placing the model and the value to search for within the braces. For example, ISIS-alerts do have a `port_id` value associated with the alert but `ifName` is not directly accessible from the `$faults[]`-array. If the name of the port was needed, it's value could be queried using a template such as:
|
||||
If some value does not exist withing the `$faults[]`-array, you may
|
||||
query fields from the database using Laravel models. You may use
|
||||
models to query additional values and use them on the template by
|
||||
placing the model and the value to search for within the braces. For
|
||||
example, ISIS-alerts do have a `port_id` value associated with the
|
||||
alert but `ifName` is not directly accessible from the
|
||||
`$faults[]`-array. If the name of the port was needed, it's value
|
||||
could be queried using a template such as:
|
||||
|
||||
```
|
||||
{{ $alert->title }}
|
||||
@ -313,7 +320,7 @@ Rule: @if ($alert->name) {{ $alert->name }} @else {{ $alert->rule }} @endif
|
||||
@endif
|
||||
```
|
||||
|
||||
#### Service Alert
|
||||
### Service Alert
|
||||
|
||||
```
|
||||
<div style="font-family:Helvetica;">
|
||||
@ -372,29 +379,29 @@ The included templates apart from the default template are:
|
||||
|
||||
## Other Examples
|
||||
|
||||
#### Microsoft Teams - Markdown
|
||||
### Microsoft Teams - Markdown
|
||||
|
||||
```
|
||||
[{{ $alert->title }}](https://your.librenms.url/device/device={{ $alert->device_id }}/)
|
||||
**Device name:** {{ $alert->sysName }}
|
||||
**Severity:** {{ $alert->severity }}
|
||||
[{{ $alert->title }}](https://your.librenms.url/device/device={{ $alert->device_id }}/)
|
||||
**Device name:** {{ $alert->sysName }}
|
||||
**Severity:** {{ $alert->severity }}
|
||||
@if ($alert->state == 0)
|
||||
**Time elapsed:** {{ $alert->elapsed }}
|
||||
**Time elapsed:** {{ $alert->elapsed }}
|
||||
@endif
|
||||
**Timestamp:** {{ $alert->timestamp }}
|
||||
**Unique-ID:** {{ $alert->uid }}
|
||||
**Timestamp:** {{ $alert->timestamp }}
|
||||
**Unique-ID:** {{ $alert->uid }}
|
||||
@if ($alert->name)
|
||||
**Rule:** {{ $alert->name }}
|
||||
**Rule:** {{ $alert->name }}
|
||||
@else
|
||||
**Rule:** {{ $alert->rule }}
|
||||
**Rule:** {{ $alert->rule }}
|
||||
@endif
|
||||
@if ($alert->faults)
|
||||
**Faults:**@foreach ($alert->faults as $key => $value) {{ $key }}: {{ $value['string'] }}
|
||||
**Faults:**@foreach ($alert->faults as $key => $value) {{ $key }}: {{ $value['string'] }}
|
||||
@endforeach
|
||||
@endif
|
||||
```
|
||||
|
||||
#### Microsoft Teams - JSON
|
||||
### Microsoft Teams - JSON
|
||||
|
||||
```
|
||||
{
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
### Rules
|
||||
# Rules
|
||||
|
||||
The simplest way of testing if an alert rule will match a device is by
|
||||
going to the device, clicking edit (the cog), select Capture. From
|
||||
@ -11,7 +11,7 @@ See [Device Troubleshooting](../Support/Device-Troubleshooting.md)
|
||||
|
||||
---
|
||||
|
||||
### Transports
|
||||
## Transports
|
||||
|
||||
You can test your transports by forcing an actual active alert to run
|
||||
regardless of the interval or delay values.
|
||||
@ -21,7 +21,7 @@ for the device id or hostname and -d for debug.
|
||||
|
||||
---
|
||||
|
||||
### Templates
|
||||
## Templates
|
||||
|
||||
It's possible to test your new template before assigning it to a
|
||||
rule. To do so you can run `./scripts/test-template.php`. The script
|
||||
|
||||
@ -34,7 +34,10 @@ You need to install an additional php module : `bcmath`
|
||||
|
||||
## Alerta
|
||||
|
||||
The [alerta](https://alerta.io) monitoring system is a tool used to consolidate and de-duplicate alerts from multiple sources for quick ‘at-a-glance’ visualisation. With just one system you can monitor alerts from many other monitoring tools on a single screen.
|
||||
The [alerta](https://alerta.io) monitoring system is a tool used to
|
||||
consolidate and de-duplicate alerts from multiple sources for quick
|
||||
‘at-a-glance’ visualisation. With just one system you can monitor
|
||||
alerts from many other monitoring tools on a single screen.
|
||||
|
||||
**Example:**
|
||||
|
||||
@ -67,10 +70,11 @@ Labels can be a fixed string or a dynamic variable from the alert.
|
||||
To set a dynamic variable your label must start with extra_ then
|
||||
complete with the name of your label (only characters, figures and
|
||||
underscore are allowed here). The value must be the name of
|
||||
the variable you want to get (you can see all the variables in
|
||||
Alerts->Notifications by clicking on the Details icon of your alert when it is pending).
|
||||
If the variable's name does not match with an existing value the
|
||||
label's value will be the string you provided just as it was a fixed string.
|
||||
the variable you want to get (you can see all the variables in
|
||||
Alerts->Notifications by clicking on the Details icon of your alert
|
||||
when it is pending). If the variable's name does not match with an
|
||||
existing value the label's value will be the string you provided just
|
||||
as it was a fixed string.
|
||||
|
||||
Multiple Alertmanager URLs (comma separated) are supported. Each
|
||||
URL will be tried and the search will stop at the first success.
|
||||
@ -94,15 +98,20 @@ If you let those value blank, no authentication will be used.
|
||||
The API transport allows to reach any service provider using POST, PUT or GET URLs
|
||||
(Like SMS provider, etc). It can be used in multiple ways:
|
||||
|
||||
- The same text built from the Alert template is available in the variable
|
||||
``` $msg ```, which can then be sent as an option to the API. Be carefull that
|
||||
HTTP GET requests are usually limited in length.
|
||||
- The API-Option fields can be directly built from the variables defined in
|
||||
[Template-Syntax](Templates.md#syntax) but without the 'alert->' prefix.
|
||||
For instance, ``` $alert->uptime ``` is available as ``` $uptime ``` in the
|
||||
API transport
|
||||
- The same text built from the Alert template is available in the
|
||||
variable
|
||||
|
||||
`$msg`, which can then be sent as an option to the API. Be carefull
|
||||
that HTTP GET requests are usually limited in length.
|
||||
|
||||
- The API-Option fields can be directly built from the variables
|
||||
defined in [Template-Syntax](Templates.md#syntax) but without the
|
||||
'alert->' prefix. For instance, `$alert->uptime` is available as
|
||||
`$uptime` in the API transport
|
||||
|
||||
- The API-Headers allows you to add the headers that the api endpoint requires.
|
||||
- The API-body allow sending data in the format required by the ApI endpoint.
|
||||
|
||||
- The API-body allow sending data in the format required by the API endpoint.
|
||||
|
||||
A few variables commonly used :
|
||||
|
||||
@ -146,7 +155,9 @@ the title and text of the alert to a screen in the Network Operation Center.
|
||||
| API URL | <http://my.example.com/wall-display>
|
||||
| API Options | title={{ $title }} <br/> msg={{ $msg }}|
|
||||
|
||||
The example below will use the API named component of my.example.com with id 1, body as json status value and headers send token authentication and content type required.
|
||||
The example below will use the API named component of my.example.com
|
||||
with id 1, body as json status value and headers send token
|
||||
authentication and content type required.
|
||||
|
||||
| Config | Example |
|
||||
| ------ | ------- |
|
||||
@ -156,8 +167,8 @@ The example below will use the API named component of my.example.com with id 1,
|
||||
| | Content-Type=application/json
|
||||
| API Body | { "status": 2 }
|
||||
|
||||
|
||||
## aspSMS
|
||||
|
||||
aspSMS is a SMS provider that can be configured by using the generic API Transport.
|
||||
You need a token you can find on your personnal space.
|
||||
|
||||
@ -170,7 +181,7 @@ You need a token you can find on your personnal space.
|
||||
| Transport type | Api |
|
||||
| API Method | POST |
|
||||
| API URL | https://soap.aspsms.com/aspsmsx.asmx/SimpleTextSMS |
|
||||
| Options | UserKey=USERKEY<br />Password=APIPASSWORD<br />Recipient=RECIPIENT<br />Originator=ORIGINATOR<br />MessageText={{ $msg }} |
|
||||
| Options | UserKey=USERKEY<br />Password=APIPASSWORD<br />Recipient=RECIPIENT<br/> Originator=ORIGINATOR<br />MessageText={{ $msg }} |
|
||||
|
||||
## Boxcar
|
||||
|
||||
@ -187,12 +198,15 @@ website and setup the transport.
|
||||
|
||||
## Browser Push
|
||||
|
||||
Browser push notifications can send a notification to the user's device even when the browser is not open.
|
||||
This requires HTTPS, the PHP GMP extension, [Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) support,
|
||||
and permissions on each device to send alerts.
|
||||
Browser push notifications can send a notification to the user's
|
||||
device even when the browser is not open. This requires HTTPS, the PHP
|
||||
GMP extension, [Push
|
||||
API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)
|
||||
support, and permissions on each device to send alerts.
|
||||
|
||||
Simply configure an alert transport and allow notification permission on the device(s) you
|
||||
wish to receive alerts on. You may disable alerts on a browser on the user preferences page.
|
||||
Simply configure an alert transport and allow notification permission
|
||||
on the device(s) you wish to receive alerts on. You may disable
|
||||
alerts on a browser on the user preferences page.
|
||||
|
||||
## Canopsis
|
||||
|
||||
@ -382,8 +396,9 @@ For using the Matrix transports, you have to create a room on the Matrix-server.
|
||||
The provided Auth_token belongs to an user, which is member of this room.
|
||||
The Message, sent to the matrix-room can be built from the variables defined in
|
||||
[Template-Syntax](Templates.md#syntax) but without the 'alert->' prefix.
|
||||
See API-Transport. The variable ``` $msg ``` is contains the result of the Alert template.
|
||||
The Matrix-Server URL is cutted before the beginning of the ``_matrix/client/r0/...`` API-part.
|
||||
See API-Transport. The variable ``` $msg ``` is contains the result of
|
||||
the Alert template.The Matrix-Server URL is cutted before the
|
||||
beginning of the ``_matrix/client/r0/...`` API-part.
|
||||
|
||||
**Example:**
|
||||
|
||||
@ -396,11 +411,13 @@ The Matrix-Server URL is cutted before the beginning of the ``_matrix/client/r0/
|
||||
|
||||
## Microsoft Teams
|
||||
|
||||
LibreNMS can send alerts to Microsoft Teams [Incoming Webhooks](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook) which are
|
||||
then posted to a specific channel. Microsoft recommends using
|
||||
[markdown](https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format#markdown-formatting-for-connector-cards) formatting for connector cards.
|
||||
Administrators can opt to [compose](https://messagecardplayground.azurewebsites.net/)
|
||||
the [MessageCard](https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference)
|
||||
LibreNMS can send alerts to Microsoft Teams [Incoming
|
||||
Webhooks](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook)
|
||||
which are then posted to a specific channel. Microsoft recommends using
|
||||
[markdown](https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format#markdown-formatting-for-connector-cards)
|
||||
formatting for connector cards. Administrators can opt to
|
||||
[compose](https://messagecardplayground.azurewebsites.net/) the
|
||||
[MessageCard](https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference)
|
||||
themselves using JSON to get the full functionality.
|
||||
|
||||
**Example:**
|
||||
@ -659,6 +676,7 @@ either local or international dialling format.
|
||||
| Mobiles | +3534567890 <br/> 0834567891 |
|
||||
|
||||
## SMSmode
|
||||
|
||||
SMSmode is a SMS provider that can be configured by using the generic API Transport.
|
||||
You need a token you can find on your personnal space.
|
||||
|
||||
@ -671,7 +689,7 @@ You need a token you can find on your personnal space.
|
||||
| Transport type | Api |
|
||||
| API Method | POST |
|
||||
| API URL | http://api.smsmode.com/http/1.6/sendSMS.do |
|
||||
| Options | accessToken=_PUT_HERE_YOUR_TOKEN_<br />numero=_PUT_HERE_DESTS_NUMBER_COMMA_SEPARATED_<br />message={{ $msg }} |
|
||||
| Options | accessToken=_PUT_HERE_YOUR_TOKEN_<br/> numero=_PUT_HERE_DESTS_NUMBER_COMMA_SEPARATED_<br />message={{ $msg }} |
|
||||
|
||||
## Splunk
|
||||
|
||||
@ -708,6 +726,7 @@ device_override_sysLocation="0", device_notes="", device_port_association_mode="
|
||||
device_max_depth="0", device_disable_notify="0", device_location="",
|
||||
device_vrf_lites="Array", device_lat="", device_lng="", -
|
||||
sysObjectID => ""; `
|
||||
```
|
||||
|
||||
Each alert will be sent as a separate message.
|
||||
|
||||
@ -801,7 +820,10 @@ located at: [https://www.twilio.com/docs/api?filter-product=sms](https://www.twi
|
||||
|
||||
## UKFast PSS
|
||||
|
||||
UKFast PSS tickets can be raised from alerts using the UKFastPSS transport. This required an [API key](https://my.ukfast.co.uk/applications) with PSS `write` permissions
|
||||
UKFast PSS tickets can be raised from alerts using the UKFastPSS
|
||||
transport. This required an [API
|
||||
key](https://my.ukfast.co.uk/applications) with PSS `write`
|
||||
permissions
|
||||
|
||||
**Example:**
|
||||
|
||||
@ -878,7 +900,8 @@ Use the Signal Mesenger for Alerts. Run the Signal CLI with the D-Bus option.
|
||||
|
||||
## SMSFeedback
|
||||
|
||||
SMSFeedback is a SAAS service, which can be used to deliver Alerts via API, using API url, Username & Password.
|
||||
SMSFeedback is a SAAS service, which can be used to deliver Alerts via
|
||||
API, using API url, Username & Password.
|
||||
|
||||
They can be in international dialling format only.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user