# InfluxDB Performance Data Module for Nagios

## Overview

The **influx_perf_api_v1** is a Nagios Event Broker (NEB) module that automatically sends Nagios performance data to InfluxDB v1.x using the InfluxDB line protocol format. This module enables real-time storage and visualization of monitoring metrics in InfluxDB for time-series analysis and dashboarding.

### What It Does

The module:
- Intercepts Nagios host and service check events
- Extracts performance data from check results
- Formats the data using InfluxDB line protocol
- Sends metrics to InfluxDB via HTTP POST using libcurl
- Supports batching multiple events to reduce network overhead
- Handles SSL/TLS connections with certificate verification
- Creates time-series measurements in InfluxDB:
  - `nagios_host_check` - Host check metrics with execution time, latency, state, and performance data
  - `nagios_service_check` - Service check metrics parsed from Nagios performance data

## Installation

### Prerequisites

- InfluxDB 1.x installed and running
- libcurl development headers (installed during setup)
- Nagios XI

### Setup Script

The setup script handles:
1. Installing InfluxDB 1.x for your Linux distribution
2. Configuring the broker module in nagios.cfg
3. Creating timestamped backups of nagios.cfg

#### Running the Setup Script

From the NagiosXI scripts directory:

```bash
/usr/local/nagiosxi/scripts/setup_influx.sh
```

Or with sudo if needed:

```bash
sudo /usr/local/nagiosxi/scripts/setup_influx.sh
```

The script automatically detects your operating system and installs InfluxDB using the appropriate package manager:
- **RHEL/CentOS/Oracle Linux**: Uses yum
- **Ubuntu/Debian**: Uses apt-get

After installation, the script:
- Creates a backup of your nagios.cfg file in `/usr/local/nagiosxi/tmp/` with an epoch timestamp
- Adds the broker module configuration to `/usr/local/nagios/etc/nagios.cfg`
- Provides instructions to restart Nagios

## Configuration

### Broker Module Line

The setup script automatically adds this line to your `nagios.cfg`:

```
broker_module=/usr/local/nagios/bin/influx_perf_api_v1.o http://localhost:8086/write?db=perfdata timeout=10 batch=10
```

### Configuration Options

The broker module accepts the following arguments:

| Argument | Description | Default | Example |
|----------|-------------|---------|---------|
| URL | InfluxDB write endpoint (required) | None | `http://localhost:8086/write?db=perfdata` |
| `timeout=N` | HTTP request timeout in seconds | 5 | `timeout=10` |
| `batch=N` | Batch N events before sending | 10 | `batch=20` |
| `ssl_verify=0\|1` | Verify SSL certificates | 1 | `ssl_verify=0` |
| `ca_cert=PATH` | Path to CA certificate bundle | None | `ca_cert=/etc/ssl/ca.pem` |
| `client_cert=PATH` | Path to client certificate | None | `client_cert=/etc/ssl/client.crt` |
| `client_key=PATH` | Path to client private key | None | `client_key=/etc/ssl/client.key` |

### Example Configurations

Basic configuration:
```
broker_module=/usr/local/nagios/bin/influx_perf_api_v1.o http://localhost:8086/write?db=perfdata timeout=10 batch=10
```

## Activating the Module

After running the setup script, restart Nagios to activate the module:

```bash
systemctl restart nagios
```

Or for Nagios XI:

```bash
systemctl restart nagios
```

Check that the module loaded successfully:

```bash
tail -f /usr/local/nagios/var/nagios.log
```

You should see log entries like:
```
influxdb: Module initialized - URL=http://localhost:8086/write?db=perfdata, timeout=10s, batch=10, ssl_verify=1
influxdb: Registered for 25 callback types
```

## Deactivating the Module

To disable the InfluxDB module without uninstalling InfluxDB:

```bash
/usr/local/nagiosxi/scripts/setup_influx.sh --deactivate
```

This will:
- Create a backup of nagios.cfg with an epoch timestamp
- Comment out the broker_module line in nagios.cfg
- Display a confirmation message

After deactivating, restart Nagios:

```bash
systemctl restart nagios
```

## Querying Data from InfluxDB

Once the module is active and Nagios is running, performance data will be written to InfluxDB. You can query the data using the InfluxDB CLI or API.

### Accessing the InfluxDB CLI

```bash
influx
```

Then switch to the perfdata database:
```sql
USE perfdata
```

### Example Queries

#### View All Host Check Data

```bash
printf "SELECT * FROM nagios_host_check" | influx -database 'perfdata'
```

Or in the InfluxDB CLI:
```sql
SELECT * FROM nagios_host_check
```

#### View All Service Check Data

```bash
printf "SELECT * FROM nagios_service_check" | influx -database 'perfdata'
```

Or in the InfluxDB CLI:
```sql
SELECT * FROM nagios_service_check
```

#### Query Recent Host Checks for a Specific Host

```bash
printf "SELECT * FROM nagios_host_check WHERE host_name='localhost' AND time > now() - 1h" | influx -database 'perfdata'
```

#### Query Service Performance Metrics

```bash
printf "SELECT * FROM nagios_service_check WHERE host_name='webserver' AND service_description='HTTP' ORDER BY time DESC LIMIT 10" | influx -database 'perfdata'
```

#### Get Average Execution Time for Host Checks

```sql
SELECT MEAN(execution_time) FROM nagios_host_check WHERE time > now() - 24h GROUP BY host_name
```

#### Get Latency Statistics for a Service

```sql
SELECT MEAN(latency), MAX(latency), MIN(latency)
FROM nagios_host_check
WHERE host_name='database-server' AND time > now() - 6h
```

#### View Available Measurements

```bash
printf "SHOW MEASUREMENTS" | influx -database 'perfdata'
```

#### View Tags for a Measurement

```bash
printf "SHOW TAG KEYS FROM nagios_host_check" | influx -database 'perfdata'
```

#### View Fields for a Measurement

```bash
printf "SHOW FIELD KEYS FROM nagios_host_check" | influx -database 'perfdata'
```

## Data Format

### Host Check Measurements

Measurement: `nagios_host_check`

**Tags:**
- `host_name` - Name of the host
- `state` - Host state (0=UP, 1=DOWN, 2=UNREACHABLE)
- `state_type` - State type (0=SOFT, 1=HARD)

**Fields:**
- `current_attempt` (integer) - Current check attempt
- `max_attempts` (integer) - Maximum check attempts
- `return_code` (integer) - Plugin return code
- `latency` (float) - Check latency in seconds
- `execution_time` (float) - Check execution time in seconds
- `output` (string) - Check output message
- Performance data fields (parsed from plugin output)

### Service Check Measurements

Measurement: `nagios_service_check`

**Tags:**
- `host_name` - Name of the host
- `service_description` - Service description

**Fields:**
- Performance data fields (parsed from plugin output, varies by service)

## Troubleshooting

### Module Not Loading

Check the logs:
```bash
tail -100 /usr/local/nagios/var/nagios.log | grep influxdb
tail -100 /var/log/messages /var/log/syslog | grep influxdb
```

Common issues:
- Incorrect InfluxDB URL
- InfluxDB service not running
- Network connectivity issues
- Missing libcurl library

### No Data in InfluxDB

Verify:
1. InfluxDB is running: `systemctl status influxdb`
2. The `perfdata` database exists: `influx -execute 'SHOW DATABASES'`
3. The module is loaded: Check nagios.log for "influxdb: Module initialized"
4. Services have performance data: Check that your Nagios checks return performance data

### Create the InfluxDB Database

If the database doesn't exist:
```bash
influx -execute 'CREATE DATABASE perfdata'
```

### Check InfluxDB Service Status

```bash
systemctl status influxdb
```

Start InfluxDB if not running:
```bash
systemctl start influxdb
systemctl enable influxdb
```

## Performance Considerations

- **Batching**: The `batch=10` parameter batches 10 events before sending to reduce network overhead
- **Timeout**: Adjust `timeout` based on network latency and InfluxDB response time
- **Memory**: Monitor Nagios memory usage if using large batch sizes

## Support

For issues or questions:
- Check `/usr/local/nagios/var/nagios.log` for module errors
- Verify InfluxDB connectivity: `curl -i http://localhost:8086/ping`
- Review InfluxDB logs: `journalctl -u influxdb -f`

## License

Copyright (c) 2026 Nagios Enterprises, LLC. All rights reserved.
