tyler.durden
/
icingabeat
mirror of https://github.com/Icinga/icingabeat.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update README.md

This commit is contained in:
Blerim Sheqa 2017-03-15 11:37:28 +01:00
parent 40d092ef76
commit 9dd0f21e77
1 changed files with 109 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

188
README.md
View File

@ -1,59 +1,63 @@
[![Build Status](https://travis-ci.org/Icinga/icingabeat.svg?branch=master)](https://travis-ci.org/Icinga/icingabeat) [![Build Status](https://travis-ci.org/Icinga/icingabeat.svg?branch=master)](https://travis-ci.org/Icinga/icingabeat)
# Icingabeat # Icingabeat
> The Beats are lightweight data shippers, written in Go, that you install on > The Beats are lightweight data shippers, written in Go, that you install on
> your servers to capture all sorts of operational data (think of logs, > your servers to capture all sorts of operational data (think of logs,
> metrics, or network packet data). The Beats send the operational data to > metrics, or network packet data). The Beats send the operational data to
> Elasticsearch, either directly or via Logstash, so it can be visualized with > Elasticsearch, either directly or via Logstash, so it can be visualized with
> Kibana. > Kibana.
Icingabeat fetches data from the Icinga 2 API and sends it either directly Icingabeat is an [Elastic Beat](https://www.elastic.co/products/beats) that
to Elasticsearch or Logstash. This Beat supports two modes: fetches data from the Icinga 2 API and sends it either directly to Elasticsearch
or Logstash. This Beat supports two modes:
**Eventstream:** Receive an eventstream from the Icinga 2 API. Events are ## Eventstream
checkresults, notifications and many other types. See below for details. There
is no polling involved when receiving an eventstream. Receive an eventstream from the Icinga 2 API. This stream includes events such
as checkresults, notifications, downtimes, acknowledgemts and many other types.
See below for details. There is no polling involved when receiving an
eventstream.
Example usage: Example usage:
* Correlate monitoring data with logging information * Correlate monitoring data with logging information
* Create dashboards in Kibana with metrics collected by Icinga 2
* Monitor notifications sent by Icinga 2 * Monitor notifications sent by Icinga 2
**Statuspoller:** The Icinga 2 API exports lots of information about the state ## Statuspoller
of the Icinga daemon. These information can be polled periodically.
The Icinga 2 API exports a lot of information about the state of the Icinga
daemon. Icingabeat can poll these information periodically.
Example usage: Example usage:
* Metrics of Icinga 2 performance * Visualize metrics of the Icinga 2 daemon
* Metrics about each enabled Icinga 2 feature * Get insights how each enable Icinga 2 feature performs
* Information about zones and endpoints * Information about zones and endpoints
## Installation ### Installation
Download and install your package from the [latest release](https://github.com/Icinga/icingabeat/releases/latest) page. Download and install your package from the
[latest release](https://github.com/Icinga/icingabeat/releases/latest) page.
## Configuration ### Configuration
Before starting Icingabeat make sure you have set up your configuration properly. Configuration of Icingabeat is splitted into 3 sections: General, Evenstream and
There are several general settings and some that are specific to the modes Statuspoller. On Linux configuration files are located at `/etc/icingabeat`
included. On Linux configuration files are located at `/etc/icingabeat`
### Connection #### General
These settings apply to both modes. They define the API endpoint to which Settings in this section apply to both modes.
Icingabeat connects to.
#### `host` ##### `host`
Hostname of your Icinga 2 API. This can be either an IP address or domain. Hostname of Icinga 2 API. This can be either an IP address or domain.
Defaults to `localhost` Defaults to `localhost`
#### `port` ##### `port`
Defaults to `5665` Defaults to `5665`
#### `user` ##### `user`
Username for the API connection. In your Icinga 2 configuration, this is a user Username to be used for the API connection. You need to create this user in your Icinga 2 configuration. Make sure that it has sufficient permissions to read the
of the object type `apiuser`. Make sure that it has sufficient permissions to data you want to collect.
read the data you want to collect. Learn more about `apiuser` permissions in the
[Icinga 2 docs](https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/icinga2-api#icinga2-api-permissions). Here is an example how an API user in your Icinga 2 configuration:
This user is allowed to receive all types of events and to query the status API:
```c++ ```c++
object ApiUser "icinga" { object ApiUser "icinga" {
password: "icinga" password: "icinga"
@ -61,79 +65,96 @@ object ApiUser "icinga" {
} }
``` ```
This user is only allowed to receive events of the type `CheckResult`
```c++
object ApiUser "icinga" {
password: "icinga"
permissions = ["events/CheckResult"]
}
```
#### `password` Learn more about the `ApiUser` and its permissions in the
[Icinga 2 docs](https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/icinga2-api#icinga2-api-permissions).
##### `password`
Defaults to `icinga` Defaults to `icinga`
#### `skip_ssl_verify` ##### `skip_ssl_verify`
Skip verification of SSL certificates. Defaults to `false` Skip verification of SSL certificates. Defaults to `false`
### Eventstream #### Eventstream
These settings are eventsream specific, they apply only to the eventstream. To Settings in this section apply to the eventstream mode. To disable the
disable evenstream completely, comment out the whole section. eventstream completely, comment out the section.
#### `types` ##### `types`
Decide which events you want to receive from the event stream. The following You can select which particular Icinga 2 events you want to receive and store.
event stream types are available, at least one must be set: The following types are available, you must set at least one:
* CheckResult * `CheckResult`
* StateChange * `StateChange`
* Notification * `Notification`
* AcknowledgementSet * `AcknowledgementSet`
* AcknowledgementCleared * `AcknowledgementCleared`
* CommentAdded * `CommentAdded`
* CommentRemoved * `CommentRemoved`
* DowntimeAdded * `DowntimeAdded`
* DowntimeRemoved * `DowntimeRemoved`
* DowntimeStarted * `DowntimeStarted`
* DowntimeTriggered * `DowntimeTriggered`
#### `filter` To set multiple types, do the following:
Event streams can be filtered by attributes using the prefix `event.` By default
no filter is set.
Only checkresults with exit status 2:
```yaml ```yaml
filter: "event.check_result.exit_status==2" types:
- CheckResult
- StateChange
- Notification
- AcknowledgementSet
- AcknowledgementCleared
``` ```
Example for the CheckResult type with the service matching the string pattern ##### `filter`
`mysql*`: Additionally to selecting the types of events, you can filter them by
attributes using the prefix `event.` and By default no filter is set.
###### Examples
Only checkresults with the exit code 2:
```yaml ```yaml
filter: 'match("mysql*", event.service)' filter: "event.check_result.exit_status==2"
``` ```
#### `retry_interval` Only checkreults of services that match `mysql*`:
Instead of stopping on connection loss, Icingabeat will try to reconnect to the ```yaml
API periodically. Defaults to `10s` filter: 'match("mysql*", event.service)'
```
### Statuspoller ##### `retry_interval`
These settings are specific to the statuspoller mode. On a connection loss Icingabeat will try to reconnect to the API periodically.
This setting defines the interval for connection retries. Defaults to `10s`
#### `interval` #### Statuspoller
Settings of this section apply to the statuspoller mode.
##### `interval`
Interval at which the status API is called. Set to `0` to disable polling. Interval at which the status API is called. Set to `0` to disable polling.
Defaults to `60s` Defaults to `60s`
### Run
To start Icingabeat, use your operating systems default commands. On Linux this
should be one of these commands, depending on the distribution you are using:
* `service icingabeat start`
* `systemctl icingabeat start` or
* `/etc/init.d/icingabeat start`
## Fields ## Fields
Icingabeat exports a bunch of fields. Have a look to the Icingabeat exports a bunch of fields. Have a look to the
[fields.asciidoc](docs/fields.asciidoc) for details. [fields.asciidoc](docs/fields.asciidoc) for details.
## Building and running manually ## Development
### Requirements ### Building and running manually
#### Requirements
* [Golang](https://golang.org/dl/) 1.7 * [Golang](https://golang.org/dl/) 1.7
### Clone #### Clone
To clone Icingabeat from the git repository, run the following commands: To clone Icingabeat from the git repository, run the following commands:
@ -143,10 +164,9 @@ cd ${GOPATH}/github.com/icinga
git clone https://github.com/icinga/icingabeat git clone https://github.com/icinga/icingabeat
``` ```
For further development, check out the [beat developer guide](https://www.elastic.co/guide/en/beats/libbeat/current/new-beat.html). For further development, check out the [beat developer guide](https://www.elastic.co/guide/en/beats/libbeat/current/new-beat.html).
### Build #### Build
Ensure that this folder is at the following location: Ensure that this folder is at the following location:
`${GOPATH}/github.com/icinga` `${GOPATH}/github.com/icinga`
@ -157,14 +177,14 @@ binary in the same directory with the name icingabeat.
make make
``` ```
### Run #### Run
To run Icingabeat with debugging output enabled, run: To run Icingabeat with debugging output enabled, run:
```shell ```shell
./icingabeat -c icingabeat.yml -e -d "*" ./icingabeat -c icingabeat.yml -e -d "*"
``` ```
### Test #### Test
To test Icingabeat, run the following command: To test Icingabeat, run the following command:
@ -182,7 +202,7 @@ make coverage-report
The test coverage is reported in the folder `./build/coverage/` The test coverage is reported in the folder `./build/coverage/`
### Update #### Update
Each beat has a template for the mapping in elasticsearch and a documentation Each beat has a template for the mapping in elasticsearch and a documentation
for the fields which is automatically generated based on `etc/fields.yml`. for the fields which is automatically generated based on `etc/fields.yml`.
@ -192,7 +212,7 @@ To generate etc/icingabeat.template.json and etc/icingabeat.asciidoc
make update make update
``` ```
### Cleanup #### Cleanup
To clean Icingabeat source code, run the following commands: To clean Icingabeat source code, run the following commands:
@ -207,7 +227,7 @@ To clean up the build directory and generated artifacts, run:
make clean make clean
``` ```
## Packaging ### Packaging
The beat frameworks provides tools to crosscompile and package your beat for The beat frameworks provides tools to crosscompile and package your beat for
different platforms. This requires [docker](https://www.docker.com/) and different platforms. This requires [docker](https://www.docker.com/) and
@ -220,3 +240,13 @@ make package
This will fetch and create all images required for the build process. The hole This will fetch and create all images required for the build process. The hole
process to finish can take several minutes. process to finish can take several minutes.
To disable snapshot packages or build specific packages, set the following
environment variables:
```shell
export SNAPSHOT=false
export TARGETS="\"linux/amd64 linux/386\""
export PACKAGES=icingabeat/deb
make package
```