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-01-02 12:02:47 +01:00
parent 207fd524c4
commit 2512cf849a
1 changed files with 134 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

175
README.md
View File

@ -1,53 +1,158 @@
# Icingabeat # Icingabeat
Welcome to Icingabeat. Icingabeat is a Beat to fetch data from the Icinga 2 API. Icingabeat has 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.
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.
Example usage:
* Metrics of Icinga 2 performance
* Metrics about each enabled Icinga 2 feature
* Information about zones and endpoints
Ensure that this folder is at the following location:
`${GOPATH}/github.com/icinga`
## Getting Started with Icingabeat ## Getting Started with Icingabeat
### Requirements ### Installation
There are no packages available yet. Please build and run Icingabeat manually.
* [Golang](https://golang.org/dl/) 1.7 ### 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.
### Init Project #### Connection
To get running with Icingabeat and also install the These settings apply to both modes. They define the API endpoint to which
dependencies, run the following command: Icingabeat connects to.
##### `host`
Hostname of your Icinga 2 API. This can be either an IP address or domain.
Defaults to `localhost`
##### `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).
This user is allowed to receive all types of events and to query the status API:
``` ```
make setup object ApiUser "icinga" {
password: "icinga"
permissions = ["events/*", "status/query"]
}
``` ```
It will create a clean git history for each major step. Note that you can always rewrite the history if you wish before pushing your changes. This user is only allowed to receive events of the type `CheckResult`
To push Icingabeat in the git repository, run the following commands:
``` ```
git remote set-url origin https://github.com/icinga/icingabeat object ApiUser "icinga" {
git push origin master password: "icinga"
permissions = ["events/CheckResult"]
}
``` ```
For further development, check out the [beat developer guide](https://www.elastic.co/guide/en/beats/libbeat/current/new-beat.html). ##### `password`
Defaults to `icinga`
### Build ##### `retry_interval`
Instead of stopping on connection loss, Icingabeat will try to reconnect to the
API periodically. Defaults to `10s`
To build the binary for Icingabeat run the command below. This will generate a binary #### Eventstream
in the same directory with the name icingabeat. These settings are eventsream specific, they apply only to the eventstream. To
disable evenstream completely, comment out the whole 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:
* 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.
Only checkresults with exit status 2:
``` ```
make filter: "event.check_result.exit_status==2"
``` ```
Example for the CheckResult type with the service matching the string pattern
`mysql*`:
```
filter: 'match("mysql*", event.service)'
```
#### StatusPoller
StatusPoller is not implemented yet.
### Run ### Run
To run Icingabeat with debugging output enabled, run: To run Icingabeat with debugging output enabled, run:
``` ```
./icingabeat -c icingabeat.yml -e -d "*" ./icingabeat -c icingabeat.yml -e -d "*"
``` ```
## Building and running manually
### Requirements
* [Golang](https://golang.org/dl/) 1.7
### Clone
To clone Icingabeat from the git repository, run the following commands:
```
mkdir -p ${GOPATH}/github.com/icinga
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
Ensure that this folder is at the following location:
`${GOPATH}/github.com/icinga`
To build the binary for Icingabeat run the command below. This will generate a
binary in the same directory with the name icingabeat.
```
make
```
### Run
To run Icingabeat with debugging output enabled, run:
```
./icingabeat -c icingabeat.yml -e -d "*"
```
### Test ### Test
@ -69,15 +174,14 @@ 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 Each beat has a template for the mapping in elasticsearch and a documentation
which is automatically generated based on `etc/fields.yml`. for the fields which is automatically generated based on `etc/fields.yml`.
To generate etc/icingabeat.template.json and etc/icingabeat.asciidoc 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:
@ -93,27 +197,16 @@ To clean up the build directory and generated artifacts, run:
make clean make clean
``` ```
### Clone
To clone Icingabeat from the git repository, run the following commands:
```
mkdir -p ${GOPATH}/github.com/icinga
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).
## Packaging ## Packaging
The beat frameworks provides tools to crosscompile and package your beat for different platforms. This requires [docker](https://www.docker.com/) and vendoring as described above. To build packages of your beat, run the following command: The beat frameworks provides tools to crosscompile and package your beat for
different platforms. This requires [docker](https://www.docker.com/) and
vendoring as described above. To build packages of your beat, run the following
command:
``` ```
make package make package
``` ```
This will fetch and create all images required for the build process. The hole process to finish can take several minutes. This will fetch and create all images required for the build process. The hole
process to finish can take several minutes.