From 8423227ae29128873e02290c547fd2c3f9f62847 Mon Sep 17 00:00:00 2001 From: localhorst Date: Sun, 4 Jan 2026 11:32:33 +0100 Subject: [PATCH] cleanup --- Dockerfile | 4 +- README.md | 95 +++++++++++++++++++++++++++++++++++----------- docker-compose.yml | 4 +- 3 files changed, 77 insertions(+), 26 deletions(-) diff --git a/Dockerfile b/Dockerfile index 576a78f..68efc0f 100644 --- a/Dockerfile +++ b/Dockerfile @@ -13,7 +13,7 @@ COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # Copy application files -COPY ttn-vegapuls-exporter.py . +COPY ttn-vegapulsair-exporter.py . COPY config.py . # Create non-root user @@ -34,4 +34,4 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \ ENV PYTHONUNBUFFERED=1 # Run the exporter -CMD ["python", "ttn-vegapuls-exporter.py"] +CMD ["python", "ttn-vegapulsair-exporter.py"] diff --git a/README.md b/README.md index 09cc2e9..21869af 100644 --- a/README.md +++ b/README.md @@ -12,31 +12,81 @@ A robust Prometheus exporter for VEGAPULS Air sensors connected via The Things N ## Metrics Exported ### Exporter Metrics -- `vegapulsair_exporter_uptime_seconds` - Exporter uptime in seconds -- `vegapulsair_exporter_requests_total` - Total number of metrics requests -- `vegapulsair_devices_total` - Total number of known devices -- `vegapulsair_devices_online` - Number of currently online devices + +| 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: + +All device metrics include a `device_id` label (e.g., `device_id="eui-04c46100008f6ffe"`). #### Status Metrics -- `vegapulsair_device_online{device_id="..."}` - Device online status (1=online, 0=offline) -- `vegapulsair_last_uplink_seconds_ago{device_id="..."}` - Seconds since last uplink + +| 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 -- `vegapulsair_distance_mm{device_id="..."}` - Distance measurement in millimeters -- `vegapulsair_temperature_celsius{device_id="..."}` - Temperature in Celsius -- `vegapulsair_inclination_degrees{device_id="..."}` - Inclination in degrees -- `vegapulsair_linear_percent{device_id="..."}` - Linear percentage -- `vegapulsair_percent{device_id="..."}` - Percentage value -- `vegapulsair_scaled_value{device_id="..."}` - Scaled measurement value -- `vegapulsair_battery_percent{device_id="..."}` - Remaining battery percentage + +| 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 -- `vegapulsair_rssi_dbm{device_id="..."}` - RSSI in dBm -- `vegapulsair_channel_rssi_dbm{device_id="..."}` - Channel RSSI in dBm -- `vegapulsair_snr_db{device_id="..."}` - Signal-to-Noise Ratio in dB + +| 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 @@ -64,14 +114,15 @@ All device metrics include a `device_id` label: 3. **Copy files:** ```bash - sudo cp ttn-vegapuls-exporter.py /opt/ttn-vegapuls-exporter/ - sudo cp config.py /opt/ttn-vegapuls-exporter/ - sudo chmod +x /opt/ttn-vegapuls-exporter/ttn-vegapuls-exporter.py + 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-vegapuls-exporter/config.py + sudo nano /opt/ttn-vegapulsair-exporter/config.py ``` Set the following required parameters: @@ -82,7 +133,7 @@ All device metrics include a `device_id` label: 5. **Set permissions:** ```bash sudo useradd -r -s /bin/false prometheus # If user doesn't exist - sudo chown -R prometheus:prometheus /opt/ttn-vegapuls-exporter + sudo chown -R prometheus:prometheus /opt/ttn-vegapulsair-exporter/ ``` 6. **Install systemd service:** diff --git a/docker-compose.yml b/docker-compose.yml index 1ffe6e1..c2d6718 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -8,7 +8,7 @@ services: # Install dependencies and run exporter entrypoint: | - sh -c "pip install --no-cache-dir paho-mqtt && python ttn-vegapuls-exporter.py" + sh -c "pip install --no-cache-dir paho-mqtt && python ttn-vegapulsair-exporter.py" working_dir: /app @@ -18,7 +18,7 @@ services: # Mount application files (read-only) volumes: - - ./ttn-vegapuls-exporter.py:/app/ttn-vegapuls-exporter.py:ro + - ./ttn-vegapulsair-exporter.py:/app/ttn-vegapulsair-exporter.py:ro - ./config.py:/app/config.py:ro # Environment variables