Update README.md
This commit is contained in:
Blerim Sheqa
parent
40d092ef76
commit
9dd0f21e77
188
README.md
188
README.md
|
|
@ -1,59 +1,63 @@
|
|||
[](https://travis-ci.org/Icinga/icingabeat)
|
||||
|
||||
# Icingabeat
|
||||
|
||||
> 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,
|
||||
> metrics, or network packet data). The Beats send the operational data to
|
||||
> Elasticsearch, either directly or via Logstash, so it can be visualized with
|
||||
> Kibana.
|
||||
|
||||
Icingabeat fetches data from the Icinga 2 API and sends it either directly
|
||||
to Elasticsearch or Logstash. This Beat supports two modes:
|
||||
Icingabeat is an [Elastic Beat](https://www.elastic.co/products/beats) that
|
||||
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
|
||||
checkresults, notifications and many other types. See below for details. There
|
||||
is no polling involved when receiving an eventstream.
|
||||
## 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:
|
||||
* Correlate monitoring data with logging information
|
||||
* Create dashboards in Kibana with metrics collected by Icinga 2
|
||||
* Monitor notifications sent by Icinga 2
|
||||
|
||||
**Statuspoller:** The Icinga 2 API exports lots of information about the state
|
||||
of the Icinga daemon. These information can be polled periodically.
|
||||
## Statuspoller
|
||||
|
||||
The Icinga 2 API exports a lot of information about the state of the Icinga
|
||||
daemon. Icingabeat can poll these information periodically.
|
||||
|
||||
Example usage:
|
||||
* Metrics of Icinga 2 performance
|
||||
* Metrics about each enabled Icinga 2 feature
|
||||
* Visualize metrics of the Icinga 2 daemon
|
||||
* Get insights how each enable Icinga 2 feature performs
|
||||
* Information about zones and endpoints
|
||||
|
||||
|
||||
## Installation
|
||||
Download and install your package from the [latest release](https://github.com/Icinga/icingabeat/releases/latest) page.
|
||||
### Installation
|
||||
Download and install your package from the
|
||||
[latest release](https://github.com/Icinga/icingabeat/releases/latest) page.
|
||||
|
||||
## Configuration
|
||||
Before starting Icingabeat make sure you have set up your configuration properly.
|
||||
There are several general settings and some that are specific to the modes
|
||||
included. On Linux configuration files are located at `/etc/icingabeat`
|
||||
### Configuration
|
||||
Configuration of Icingabeat is splitted into 3 sections: General, Evenstream and
|
||||
Statuspoller. On Linux configuration files are located at `/etc/icingabeat`
|
||||
|
||||
### Connection
|
||||
These settings apply to both modes. They define the API endpoint to which
|
||||
Icingabeat connects to.
|
||||
#### General
|
||||
Settings in this section apply to both modes.
|
||||
|
||||
#### `host`
|
||||
Hostname of your Icinga 2 API. This can be either an IP address or domain.
|
||||
##### `host`
|
||||
Hostname of Icinga 2 API. This can be either an IP address or domain.
|
||||
Defaults to `localhost`
|
||||
|
||||
#### `port`
|
||||
##### `port`
|
||||
Defaults to `5665`
|
||||
|
||||
#### `user`
|
||||
Username for the API connection. In your Icinga 2 configuration, this is a user
|
||||
of the object type `apiuser`. Make sure that it has sufficient permissions to
|
||||
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).
|
||||
##### `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
|
||||
data you want to collect.
|
||||
|
||||
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++
|
||||
object ApiUser "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`
|
||||
|
||||
#### `skip_ssl_verify`
|
||||
##### `skip_ssl_verify`
|
||||
Skip verification of SSL certificates. Defaults to `false`
|
||||
|
||||
### Eventstream
|
||||
These settings are eventsream specific, they apply only to the eventstream. To
|
||||
disable evenstream completely, comment out the whole section.
|
||||
#### Eventstream
|
||||
Settings in this section apply to the eventstream mode. To disable the
|
||||
eventstream completely, comment out the section.
|
||||
|
||||
#### `types`
|
||||
Decide which events you want to receive from the event stream. The following
|
||||
event stream types are available, at least one must be set:
|
||||
##### `types`
|
||||
You can select which particular Icinga 2 events you want to receive and store.
|
||||
The following types are available, you must set at least one:
|
||||
|
||||
* CheckResult
|
||||
* StateChange
|
||||
* Notification
|
||||
* AcknowledgementSet
|
||||
* AcknowledgementCleared
|
||||
* CommentAdded
|
||||
* CommentRemoved
|
||||
* DowntimeAdded
|
||||
* DowntimeRemoved
|
||||
* DowntimeStarted
|
||||
* DowntimeTriggered
|
||||
* `CheckResult`
|
||||
* `StateChange`
|
||||
* `Notification`
|
||||
* `AcknowledgementSet`
|
||||
* `AcknowledgementCleared`
|
||||
* `CommentAdded`
|
||||
* `CommentRemoved`
|
||||
* `DowntimeAdded`
|
||||
* `DowntimeRemoved`
|
||||
* `DowntimeStarted`
|
||||
* `DowntimeTriggered`
|
||||
|
||||
#### `filter`
|
||||
Event streams can be filtered by attributes using the prefix `event.` By default
|
||||
no filter is set.
|
||||
To set multiple types, do the following:
|
||||
|
||||
|
||||
Only checkresults with exit status 2:
|
||||
```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
|
||||
`mysql*`:
|
||||
##### `filter`
|
||||
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
|
||||
filter: 'match("mysql*", event.service)'
|
||||
filter: "event.check_result.exit_status==2"
|
||||
```
|
||||
|
||||
#### `retry_interval`
|
||||
Instead of stopping on connection loss, Icingabeat will try to reconnect to the
|
||||
API periodically. Defaults to `10s`
|
||||
Only checkreults of services that match `mysql*`:
|
||||
```yaml
|
||||
filter: 'match("mysql*", event.service)'
|
||||
```
|
||||
|
||||
### Statuspoller
|
||||
These settings are specific to the statuspoller mode.
|
||||
##### `retry_interval`
|
||||
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.
|
||||
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
|
||||
Icingabeat exports a bunch of fields. Have a look to the
|
||||
[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
|
||||
|
||||
### Clone
|
||||
#### Clone
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
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:
|
||||
`${GOPATH}/github.com/icinga`
|
||||
|
||||
|
|
@ -157,14 +177,14 @@ binary in the same directory with the name icingabeat.
|
|||
make
|
||||
```
|
||||
|
||||
### Run
|
||||
#### Run
|
||||
To run Icingabeat with debugging output enabled, run:
|
||||
|
||||
```shell
|
||||
./icingabeat -c icingabeat.yml -e -d "*"
|
||||
```
|
||||
|
||||
### Test
|
||||
#### Test
|
||||
|
||||
To test Icingabeat, run the following command:
|
||||
|
||||
|
|
@ -182,7 +202,7 @@ make coverage-report
|
|||
|
||||
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
|
||||
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
|
||||
```
|
||||
|
||||
### Cleanup
|
||||
#### Cleanup
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## Packaging
|
||||
### Packaging
|
||||
|
||||
The beat frameworks provides tools to crosscompile and package your beat for
|
||||
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
|
||||
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
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue