So what’s the deal with it anyways? Imagine that you want to connect to the API and receive check results, downtimes, comments, acknowledgements, etc for your own backend. Which in turn would mean you could proxy-forward these metrics to your own backend (ElasticSearch, Redis, MySQL, Graphite, InfluxDB, Logstash, Graylog, etc) or tool-stack (StackStorm, PagerDuty, etc.). Or correlate multiple events into one action (auto-acknowledge a problem based on multiple check results?).
There are many possible use cases – if you are familiar with Icinga 1.x and the “oscp” commands to forward check result events to your umbrella monitoring (SCOM, Tivoli, etc), the API event streams are a yet better replacement too. It will also help troubleshooting running check – fetch a live stream of check result events and analyse your problem :)
Send a POST request to /v1/events and pass the following as URL parameter:
- queue name
- types (one or more event types, e.g. CheckResult, Notification, etc)
- filter (match on event. attributes)
More details can be found in the snapshot documentation. Ready to test-drive the API? The Vagrant boxes are running the latest snapshots allowing to easily connect to the REST API – check the screencast :-)
$ git clone https://github.com/Icinga/icinga-vagrant.git && cd icinga-vagrant $ cd icinga2x $ vagrant up
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://192.168.33.5:5665/v1/events?queue=more&types=CheckResult&types=Notification&types=DowntimeTriggered' $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://192.168.33.5:5665/v1/events?queue=cr&types=CheckResult&filter=event.check_result.state!=ServiceOK'
Update 2015-11-06: Added required Accept header to curl examples.