283 lines
10 KiB
Markdown
283 lines
10 KiB
Markdown
# TTN VEGAPULS Air Prometheus Exporter
|
|
|
|
A robust Prometheus exporter for VEGAPULS Air sensors connected via The Things Network (TTN). This exporter provides reliable monitoring with automatic reconnection, uplink caching, and timeout detection.
|
|
|
|
## Features
|
|
|
|
- **Uplink Caching**: Stores historical data with timestamps for each device
|
|
- **Timeout Detection**: Automatically detects offline sensors (configurable, default 19 hours)
|
|
- **Better Error Handling**: Comprehensive logging and error recovery
|
|
- **Multiple Device Support**: Automatically handles multiple sensors
|
|
|
|
## Metrics Exported
|
|
|
|
### Exporter Metrics
|
|
|
|
| Metric | Type | Description | Example Value |
|
|
|---------------------------------------|---------|------------------------------------|---------------|
|
|
| `vegapulsair_exporter_uptime_seconds` | gauge | Exporter uptime in seconds | `506` |
|
|
| `vegapulsair_exporter_requests_total` | counter | Total number of metrics requests | `39` |
|
|
| `vegapulsair_devices_total` | gauge | Total number of known devices | `1` |
|
|
| `vegapulsair_devices_online` | gauge | Number of currently online devices | `1` |
|
|
|
|
### Per-Device Metrics
|
|
|
|
All device metrics include a `device_id` label (e.g., `device_id="eui-04c46100008f6ffe"`).
|
|
|
|
#### Status Metrics
|
|
|
|
| Metric | Type | Description | Example Value |
|
|
|--------------------------------------------------------|-------|--------------------------------------------|---------------|
|
|
| `vegapulsair_device_online{device_id="..."}` | gauge | Device online status (1=online, 0=offline) | `1` |
|
|
| `vegapulsair_last_uplink_seconds_ago{device_id="..."}` | gauge | Seconds since last uplink | `4` |
|
|
|
|
#### Sensor Measurements
|
|
|
|
| Metric | Type | Description | Example Value |
|
|
|----------------------------------------------------|---------|--------------------------------------------------|---------------|
|
|
| `vegapulsair_distance_mm{device_id="..."}` | gauge | Distance measurement in millimeters | `0.788` |
|
|
| `vegapulsair_temperature_celsius{device_id="..."}` | gauge | Temperature in Celsius | `190` |
|
|
| `vegapulsair_inclination_degrees{device_id="..."}` | gauge | Inclination in degrees | `3` |
|
|
| `vegapulsair_linear_percent{device_id="..."}` | gauge | Linear percentage (0-10000, divide by 100 for %) | `4743` |
|
|
| `vegapulsair_percent{device_id="..."}` | gauge | Percentage value (0-10000, divide by 100 for %) | `4743` |
|
|
| `vegapulsair_scaled_value{device_id="..."}` | gauge | Scaled measurement value | `1423.024` |
|
|
| `vegapulsair_scaled_unit{device_id="..."}` | gauge | Unit code for scaled value | `41` |
|
|
| `vegapulsair_packet_identifier{device_id="..."}` | counter | Packet sequence identifier | `12` |
|
|
| `vegapulsair_battery_percent{device_id="..."}` | gauge | Remaining battery percentage | `99` |
|
|
| `vegapulsair_unit{device_id="..."}` | gauge | Unit code for distance measurement | `45` |
|
|
| `vegapulsair_temperature_unit{device_id="..."}` | gauge | Unit code for temperature | `32` |
|
|
|
|
#### LoRaWAN Metadata
|
|
|
|
| Metric | Type | Description | Example Value |
|
|
|-------------------------------------------------|-------|-------------------------------|---------------|
|
|
| `vegapulsair_rssi_dbm{device_id="..."}` | gauge | RSSI in dBm (signal strength) | `42` |
|
|
| `vegapulsair_channel_rssi_dbm{device_id="..."}` | gauge | Channel RSSI in dBm | `42` |
|
|
| `vegapulsair_snr_db{device_id="..."}` | gauge | Signal-to-Noise Ratio in dB | `4.2` |
|
|
|
|
### Example Output
|
|
|
|
```prometheus
|
|
vegapulsair_exporter_uptime_seconds 506
|
|
vegapulsair_exporter_requests_total 39
|
|
vegapulsair_devices_total 1
|
|
vegapulsair_devices_online 1
|
|
vegapulsair_device_online{device_id="eui-04c46100008f6ffe"} 1
|
|
vegapulsair_last_uplink_seconds_ago{device_id="eui-04c46100008f6ffe"} 4
|
|
vegapulsair_distance_mm{device_id="eui-04c46100008f6ffe"} 0.788
|
|
vegapulsair_temperature_celsius{device_id="eui-04c46100008f6ffe"} 190
|
|
vegapulsair_inclination_degrees{device_id="eui-04c46100008f6ffe"} 3
|
|
vegapulsair_linear_percent{device_id="eui-04c46100008f6ffe"} 4743
|
|
vegapulsair_percent{device_id="eui-04c46100008f6ffe"} 4743
|
|
vegapulsair_scaled_value{device_id="eui-04c46100008f6ffe"} 1423.024
|
|
vegapulsair_scaled_unit{device_id="eui-04c46100008f6ffe"} 41
|
|
vegapulsair_packet_identifier{device_id="eui-04c46100008f6ffe"} 12
|
|
vegapulsair_battery_percent{device_id="eui-04c46100008f6ffe"} 99
|
|
vegapulsair_unit{device_id="eui-04c46100008f6ffe"} 45
|
|
vegapulsair_temperature_unit{device_id="eui-04c46100008f6ffe"} 32
|
|
vegapulsair_rssi_dbm{device_id="eui-04c46100008f6ffe"} 42
|
|
vegapulsair_channel_rssi_dbm{device_id="eui-04c46100008f6ffe"} 42
|
|
vegapulsair_snr_db{device_id="eui-04c46100008f6ffe"} 4.2
|
|
```
|
|
|
|
### Metric Notes
|
|
|
|
- **Percentage values** (`linear_percent`, `percent`): These are stored as integers 0-10000. To get actual percentage, divide by 100:
|
|
- Example: `4743 / 100 = 47.43%`
|
|
- **Unit codes**: VEGAPULS Air uses numeric codes to indicate measurement units. Refer to VEGAPULS Air documentation for unit code meanings.
|
|
- **RSSI**: Typical values range from -120 dBm (very weak) to -30 dBm (excellent)
|
|
- **SNR**: Positive values indicate good signal quality. Values below -15 dB may indicate issues.
|
|
|
|
## Requirements
|
|
|
|
- Python 3.7 or higher
|
|
- `paho-mqtt` library
|
|
|
|
## Installation
|
|
|
|
### Option 1: Manual Installation
|
|
|
|
1. **Install Python dependencies:**
|
|
```bash
|
|
pip install paho-mqtt --break-system-packages
|
|
# Or use a virtual environment:
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
pip install paho-mqtt
|
|
```
|
|
|
|
2. **Create installation directory:**
|
|
```bash
|
|
sudo mkdir -p /opt/ttn-vegapuls-exporter
|
|
cd /opt/ttn-vegapuls-exporter
|
|
```
|
|
|
|
3. **Copy files:**
|
|
```bash
|
|
sudo cp ttn-vegapulsair-exporter.py /opt/ttn-vegapulsair-exporter
|
|
sudo cp config.py /opt/ttn-vegapulsair-exporter/
|
|
sudo chmod +x /opt/ttn-vegapulsair-exporter/ttn-vegapulsair-exporter.py
|
|
sudo chmod +x /opt/ttn-vegapulsair-exporter/config.py
|
|
```
|
|
|
|
4. **Configure the exporter:**
|
|
```bash
|
|
sudo nano /opt/ttn-vegapulsair-exporter/config.py
|
|
```
|
|
|
|
Set the following required parameters:
|
|
- `ttn_user`: Your TTN application ID (format: `your-app-id@ttn`)
|
|
- `ttn_key`: Your TTN API key (get from TTN Console)
|
|
- `ttn_region`: Your TTN region (EU1, NAM1, AU1, etc.)
|
|
|
|
5. **Set permissions:**
|
|
```bash
|
|
sudo useradd -r -s /bin/false prometheus # If user doesn't exist
|
|
sudo chown -R prometheus:prometheus /opt/ttn-vegapulsair-exporter/
|
|
```
|
|
|
|
6. **Install systemd service:**
|
|
```bash
|
|
sudo cp ttn-vegapulsair-exporter.service /etc/systemd/system/
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable ttn-vegapulsair-exporter.service
|
|
sudo systemctl start ttn-vegapulsair-exporter.service
|
|
```
|
|
|
|
7. **Check status:**
|
|
```bash
|
|
sudo systemctl status ttn-vegapulsair-exporter.service
|
|
sudo journalctl -u ttn-vegapulsair-exporter.service -f
|
|
```
|
|
|
|
### Option 2: Docker Installation
|
|
See `docker-compose.yml`.
|
|
|
|
## Configuration
|
|
|
|
Edit `config.py` to customize the exporter:
|
|
|
|
```python
|
|
# HTTP Server configuration
|
|
hostName = "0.0.0.0" # Listen address
|
|
serverPort = 9106 # Port for metrics endpoint
|
|
|
|
# TTN Configuration
|
|
ttn_user = "your-app@ttn"
|
|
ttn_key = "NNSXS...." # From TTN Console
|
|
ttn_region = "EU1"
|
|
|
|
# Timeout configuration
|
|
sensor_timeout_hours = 19 # Mark sensor offline after N hours
|
|
|
|
# Logging
|
|
log_level = "INFO" # DEBUG, INFO, WARNING, ERROR, CRITICAL
|
|
```
|
|
|
|
### Getting TTN Credentials
|
|
|
|
1. Log in to [TTN Console](https://console.cloud.thethings.network/)
|
|
2. Select your application
|
|
3. Go to **Integrations** → **MQTT**
|
|
4. Copy the following:
|
|
- **Username**: Your application ID (format: `your-app-id@ttn`)
|
|
- **Password**: Generate an API key with "Read application traffic" permission
|
|
- **Region**: Your cluster region (visible in the URL, e.g., `eu1`)
|
|
|
|
## Prometheus Configuration
|
|
|
|
Add to your `prometheus.yml`:
|
|
|
|
```yaml
|
|
scrape_configs:
|
|
- job_name: 'vegapuls-air'
|
|
static_configs:
|
|
- targets: ['localhost:9106']
|
|
scrape_interval: 60s
|
|
scrape_timeout: 10s
|
|
```
|
|
|
|
### Example Prometheus Alerts
|
|
|
|
See `prometheus-alerts.yml`.
|
|
|
|
## Troubleshooting
|
|
|
|
### No Metrics Appearing
|
|
|
|
1. **Check MQTT connection:**
|
|
```bash
|
|
sudo journalctl -u ttn-vegapuls-exporter.service | grep MQTT
|
|
```
|
|
|
|
You should see: `Successfully connected to TTN MQTT broker`
|
|
|
|
2. **Verify TTN credentials:**
|
|
- Ensure `ttn_user` format is correct: `your-app-id@ttn`
|
|
- Verify API key has "Read application traffic" permission
|
|
- Check region matches your TTN cluster
|
|
|
|
3. **Test metrics endpoint:**
|
|
```bash
|
|
curl http://localhost:9106/metrics
|
|
```
|
|
|
|
### MQTT Disconnections
|
|
|
|
The exporter now handles disconnections automatically with exponential backoff. Check logs:
|
|
|
|
```bash
|
|
sudo journalctl -u ttn-vegapuls-exporter.service -f
|
|
```
|
|
|
|
If disconnections persist:
|
|
- Check network connectivity to TTN
|
|
- Verify firewall allows outbound port 8883
|
|
- Ensure system time is correct (TLS certificates)
|
|
|
|
### Devices Not Appearing
|
|
|
|
1. **Verify devices are sending uplinks:**
|
|
- Check TTN Console → Applications → Your App → Live Data
|
|
- Ensure devices are joined and transmitting
|
|
|
|
2. **Check user ID:**
|
|
- `ttn_user` must match your TTN application ID exactly
|
|
|
|
3. **Verify payload decoder:**
|
|
- Devices must have decoded payload in TTN
|
|
- Check TTN Payload Formatter is configured
|
|
|
|
### Debug Mode
|
|
|
|
Enable debug logging in `config.py`:
|
|
|
|
```python
|
|
log_level = "DEBUG"
|
|
```
|
|
|
|
This will show:
|
|
- All MQTT messages received
|
|
- Cache updates
|
|
- Device status changes
|
|
- Detailed error information
|
|
|
|
### Data Flow
|
|
|
|
```
|
|
VEGAPULS Air Sensor
|
|
↓
|
|
LoRaWAN Gateway
|
|
↓
|
|
The Things Network
|
|
↓
|
|
MQTT Broker (TLS)
|
|
↓
|
|
Exporter (caches data)
|
|
↓
|
|
Prometheus (scrapes metrics)
|
|
```
|
|
|
|
## License
|
|
|
|
See [LICENSE](LICENSE) file for details. |