Skip to content

Commit

Permalink
Merge pull request #39 from wbollock/docs/update_readme
Browse files Browse the repository at this point in the history 
docs: update readme
  • Loading branch information
@wbollock
wbollock authored Mar 8, 2023
2 parents 2ea07f7 + c235803 commit bad7b23
Showing 1 changed file with 91 additions and 35 deletions.
126 changes: 91 additions & 35 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,15 @@ This exporter does not output Nagios check results as Prometheus metrics; it is

- [nagios\_exporter](#nagios_exporter)
- [Table of Contents](#table-of-contents)
- [Configuration](#configuration)
- [Nagios Core 3/4 support](#nagios-core-34-support)
- [Installation](#installation)
- [Debian/RPM package](#debianrpm-package)
- [Binary](#binary)
- [Source](#source)
- [Configuration](#configuration)
- [Configuration File](#configuration-file)
- [CLI](#cli)
- [Nagios Core 3/4 support](#nagios-core-34-support)
- [Metrics](#metrics)
- [Grafana](#grafana)
- [Troubleshooting](#troubleshooting)
- [NagiosXI](#nagiosxi)
Expand All @@ -45,6 +48,35 @@ This exporter does not output Nagios check results as Prometheus metrics; it is
- [Releasing](#releasing)
- [Contributors ✨](#contributors-)

## Installation

### Debian/RPM package

Substitute `{{ version }}` for your desired release.

```bash
wget https://github.com/wbollock/nagios_exporter/releases/download/v{{ version }}/prometheus-nagios-exporter_{{ version }}_linux_amd64.{deb,rpm}
{dpkg,rpm} -i prometheus-nagios-exporter_{{ version }}_linux_amd64.{deb,rpm}
```

### Binary

```bash
wget https://github.com/wbollock/nagios_exporter/releases/download/v{{ version }}/nagios_exporter_{{ version }}_Linux_x86_64.tar.gz
tar xvf nagios_exporter_{{ version }}_Linux_x86_64.tar.gz
./nagios_exporter/prometheus-nagios-exporter
```

### Source

```bash
wget https://github.com/wbollock/nagios_exporter/archive/refs/tags/v{{ version }}.tar.gz
tar xvf nagios_exporter-{{ version }}.tar.gz
cd ./nagios_exporter-{{ version }}
go build nagios_exporter.go
./nagios_exporter.go
```

## Configuration

Create a simple `config.toml` in `/etc/prometheus-nagios-exporter` with your Nagios API key:
Expand All @@ -55,20 +87,35 @@ Create a simple `config.toml` in `/etc/prometheus-nagios-exporter` with your Nag
APIKey = ""
```

By default this will point to `http://localhost`, but a remote address can be specified with `--nagios.scrape-uri`. The default port is `9927`, but can be changed with `--web.listen-address`.
### Configuration File

SSL support is included for scraping remote Nagios endpoints, and SSL verification can be enabled/disabled with `--nagios.ssl-verify`. A scrape timeout value is also available with `--nagios.timeout`.
In TOML format.

```bash
./nagios_exporter --nagios.scrape-uri https://<my-tls-url> --nagios.ssl-verify true --nagios.timeout 5
```
| Environment Variable | Description | Default | Required |
|:----------------------------:|-----------------------------------------------------------------|-----------|:--------:|
| `APIKey` | The NagiosXI API key if exporting NagiosXI api-specific metrics | | ❌ |

### CLI

To see all available configuration flags:

```bash
./prometheus-nagios-exporter -h
```

| CLI Flag | Description | Default | Required |
|:------------------------------:|----------------------------------------------------------------|-----------|:--------:|
| `---config.path` | Configuration file path, only for API key | /etc/prometheus-nagios-exporter/config.toml | ❌ |
| `--log.level` | Minimum log level like "debug" or "info" | info | ❌ |
| `--nagios.check-updates` | Enable optional `nagios_update_available_info` metric | false | ❌ |
| `--nagios.config_path` | Nagios configuration path for use with nagiostats binary | `/usr/local/nagios/etc/nagios.cfg ` | ❌ |
| `--nagios.scrape-uri` | Nagios application address to scrape | `http://localhost ` | ❌ |
| `--nagios.ssl-verify` | SSL certificate validation | false | ❌ |
| `--nagios.stats_binary` | Path of nagiostats binary and configuration (e.g `/usr/local/nagios/bin/nagiostats`) | | ❌ |
| `--nagios.timeout` | Timeout for querying Nagios API in seconds (on big installations I recommend ~60) | `5` | ❌ |
| `--web.listen-address` |Address to listen on for telemetry (scrape port) | `9927` | ❌ |
| `--web.telemetry-path` | Path under which to expose metrics | `/metrics` | ❌ |

### Nagios Core 3/4 support

This exporter also supports Nagios Core 3/4 and CheckMK, albeit with a subset of metrics and reliance on the `nagiosstats` binary. There is no RESTful API for either monitoring platform, so the exporter must be run directly on the Nagios host and have access to execute `nagiostats`.
Expand All @@ -92,34 +139,43 @@ Example usage:

Note that this flag nullifies all others. It cannot be used in conjunction with the Nagios XI API.

## Installation

### Debian/RPM package

Substitute `{{ version }}` for your desired release.

```bash
wget https://github.com/wbollock/nagios_exporter/releases/download/v{{ version }}/prometheus-nagios-exporter_{{ version }}_linux_amd64.{deb,rpm}
{dpkg,rpm} -i prometheus-nagios-exporter_{{ version }}_linux_amd64.{deb,rpm}
```

### Binary

```bash
wget https://github.com/wbollock/nagios_exporter/releases/download/v{{ version }}/nagios_exporter_{{ version }}_Linux_x86_64.tar.gz
tar xvf nagios_exporter_{{ version }}_Linux_x86_64.tar.gz
./nagios_exporter/prometheus-nagios-exporter
```

### Source

```bash
wget https://github.com/wbollock/nagios_exporter/archive/refs/tags/v{{ version }}.tar.gz
tar xvf nagios_exporter-{{ version }}.tar.gz
cd ./nagios_exporter-{{ version }}
go build nagios_exporter.go
./nagios_exporter.go
```
## Metrics

<details close>

<summary>Click to expand metrics</summary>

| Metric Name | Description | Type |
|:--------------------------------:|:----------------------------------------------------:|:---------:|
| `nagios_build_info` | Nagios exporter build information | gauge |
| `nagios_host_checks_execution` | Host check execution | histogram |
| `nagios_host_checks_latency` | Host check latency | histogram |
| `nagios_host_checks_minutes` | Host checks over time | histogram |
| `nagios_host_checks_performance_seconds` | Host checks performance | gauge |
| `nagios_hosts_acknowledges_total` | Amount of host problems acknowledged | gauge |
| `nagios_hosts_checked_total` | Amount of hosts checked | gauge |
| `nagios_hosts_downtime_total` | Amount of hosts in downtime | gauge |
| `nagios_hosts_status_total` | Amount of hosts in different states | gauge |
| `nagios_hosts_total` | Amount of hosts present in configuration | gauge |
| `nagios_service_checks_execution` | Service check execution | histogram |
| `nagios_service_checks_latency` | Service check latency | histogram |
| `nagios_service_checks_minutes` | Service checks over time | histogram |
| `nagios_service_checks_performance_seconds` | Service checks performance | gauge |
| `nagios_services_acknowledges_total` | Amount of service problems acknowledged | gauge |
| `nagios_services_checked_total` | Amount of services checked | gauge |
| `nagios_services_downtime_total` | Amount of services in downtime | gauge |
| `nagios_services_status_total` | Amount of services in different states | gauge |
| `nagios_services_total` | Amount of services present in configuration | gauge |
| `nagios_up` | Whether Nagios can be reached | gauge |
| `nagios_update_available_info` | NagiosXI update is available (optional metric!) | gauge |
| `nagios_users_privileges_total` | Amount of admin or regular users | gauge |
| `nagios_users_status_total` | Amount of disabled or enabled users | gauge |
| `nagios_users_total` | Amount of users present on the system | gauge |
| `nagios_version_info` | Nagios version information | gauge |

`nagios_update_available_info` is optional because the user may not want their Nagios server scraping the external version webpage every `scrape_interval`.

</details>

## Grafana

Expand Down

0 comments on commit bad7b23

Please sign in to comment.