OpenNMS Elastic Search ReST plugin

The OpenNMS Elastic Search ReST plugin provides an interface to forward events, alarms and alarm change events generated by the Alarm Change Notifier Plugin to Elastic Search (https://github.com/elastic/elasticsearch)

This plugin uses the Elastic Search ReST interface and can interact cloud hosted with Elastic Search instances. The interface has been tested with Elastic Search 2.x.

The OpenNMS Elastic Search ReST plugin uses the Jest library (https://github.com/searchbox-io/Jest) to access the Elastic Search ReST interface.

Please note that a previous OpenNMS Elastic Search interface used the Camel Elastic Search plugin (http://camel.apache.org/elasticsearch.html) to talk directly to the internal Elastic Search API. This was limited to Elastic Search 1.x and could not work with cloud hosted Elastic Search instances because they only expose the ReST interface.

configuration

Configuration is held in

/etc/org.opennms.plugin.elasticsearch.rest.forwarder.cfg

With the following properties (defaults shown will be used if file is not present)

## url of elastic search ReST interface
elasticsearchUrl=http://localhost:9200

## username and password to access Elastic Search
esusername=""

espassword=""

## log the event description - often omitted because lots of redundant text
logEventDescription=true

## archive raw OpenNMS events
archiveRawEvents=true

## archive OpenNMS alarms
archiveAlarms=true

## archive OpenNMS alarm change events
archiveAlarmChangeEvents=true

## for alarm change events we can choose to archive the detailed alarm values but this is expensive. Set false in production.
archiveOldAlarmValues=true

archiveNewAlarmValues=true

Index Definitions

Three indexes are created; one for alarms, one for alarm change events and one for raw events. Alarms and alarm change events are only saved if the alarm-change-notifier plugin is also installed to generate alarm change events from the OpenNMS alarms table. The index names are of the form;

<name>-<date>/type/id

For example

a) Alarms

opennms-alarms-2016.08/alarmdata/1823

b) Alarm Change Events

opennms-events-alarmchange-2016.08/eventdata/11549

c) Raw OpenNMS events (not including alarm change events)

opennms-events-raw-2016.08/eventdata/11549

Viewing events using Kibana Sense

Kibana Sense is a Kibana app which allows you to run queries directly against Elastic Search (https://www.elastic.co/guide/en/sense/current/installing.html)

If you install Kibana Sense you can use the following commands to view the alarms and events sent to Elastic Search You should review the Elastic Search rest api documentation to understand how searches are specified. (See https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html)

Example searches to use in Kibana Sense

Search all the alarms indexes

GET /opennms-alarms-*/_search

Get all of the alarms indexes

GET /opennms-alarms-*/

Get a specific alarm id from the 2016.08 index

GET opennms-alarms-2016.08/alarmdata/1823

Delete all alarm indexes

DELETE /opennms-alarms-*/

Search all the events indexes

GET /opennms-events-*/_search

Search all the raw events indexes

GET /opennms-events-raw*/_search

Delete all the events indexes

DELETE /opennms-events-*/

Get all the raw events indexes

GET /opennms-events-raw*/

Get all the alarmchange event indexes

GET /opennms-events-alarmchange-*/

Search all the alarm change event indexes

GET opennms-events-alarmchange-*/_search

Get a specific alarm change event

GET opennms-events-alarmchange-2016.08/eventdata/11549

Loading Historical Events

It is possible to load historical OpenNMS events into Elastic Search from the OpenNMS database using a karaf consol command. The command uses the OpenNMS Events ReST interface to retrieve a set number of historical events and forward them to Elastic Search. Because we are using the ReST interface it is also possible to contact a remote OpenNMS and download its events into Elastic Search by using the correct remote URL and credentials.

open karaf command prompt using
ssh -p 8101 admin@localhost

To send historic events to Elastic Search use a command of the form:

karaf> elastic-search:send-historic-events limit offset [ onms-username onms-password onms-url use-node-label ]

The mandatory parameters are

  • limit - Limit of number of events to send

  • offset - Offset for starting list of events

(note that the limit parameter works in multiples of 10 and may send more than the limit to round to 10 events)

The following parameters are optional and will use defaults if not set

  • onms-username - ReST password for opennms (default: admin)

  • onms-password - ReST username for opennms (default: admin)

  • onms-url - URL of OpenNMS ReST interface to retrieve events to send (default: http://localhost:8980)

  • use-node-label - If false local node cache will get nodelabel for nodeid. If true will use remote nodelabel (default: false)

If you are uploading events from the local machine on which you are running this command, you should use the local node cache as this supplies a number of node values including the nodelabel. If you are uploading from a remote machine you should use the remote node label and not the local node cache. Only the remote nodelabel is provided in this case.

Command examples:

elastic-search:send-historic-events 100 0 admin admin http://localhost:8980 false

This retrieves 110 alarms from the local machine using the local node cache for node label

elastic-search:send-historic-events 100 0 demo demo http://demo.opennms.org true

This retrieves 110 alarms from the remote machine using the remote node labels