2024-06-26 01:31:01 -07:00
# Meshtastic Metrics Exporter
The `meshtastic-metrics-exporter` is a tool designed to export nearly all available data from an MQTT server to a
Prometheus server. It comes with a pre-configured Grafana dashboard connected to both data sources, allowing users to
start creating dashboards immediately.
## Features
- Exports a comprehensive set of metrics from an MQTT server to Prometheus.
2024-06-28 12:17:23 -07:00
- Comes with a Grafana dashboard configured to connect to both Prometheus and Postgres data sources.
- Stores node details (ID, short/long name, hardware details, and client type) in a Postgres server, which is also part of
2024-06-26 01:31:01 -07:00
the package.
- Configuration via a `.env` file.
## Exported Metrics
2024-07-01 03:05:48 -07:00
🏷️ Common Labels: `node_id, short_name, long_name, hardware_model, role`
Label Notation:
- 🏷️: Indicates that all common labels are used.
- 🏷️ (source): Indicates that all common labels are used, prefixed with "source_" (e.g., source_node_id, source_short_name, etc.).
- 🏷️ (destination): Indicates that all common labels are used, prefixed with "destination_" (e.g., destination_node_id, destination_short_name, etc.).
2024-06-26 01:31:01 -07:00
The following is a list of metrics exported by the `meshtastic-metrics-exporter` :
| Metric Name | Description | Type | Labels |
|-----------------------------------|------------------------------------------------------------------------------|-----------|--------------------------------------|
2024-07-01 03:05:48 -07:00
| text_message_app_length | Length of text messages processed by the app | Histogram | 🏷️ |
| device_latitude | Device latitude | Gauge | 🏷️ |
| device_longitude | Device longitude | Gauge | 🏷️ |
| device_altitude | Device altitude | Gauge | 🏷️ |
| device_position_precision | Device position precision | Gauge | 🏷️ |
| telemetry_app_ch1_voltage | Voltage measured by the device on channel 1 | Gauge | 🏷️ |
| telemetry_app_ch1_current | Current measured by the device on channel 1 | Gauge | 🏷️ |
| telemetry_app_ch2_voltage | Voltage measured by the device on channel 2 | Gauge | 🏷️ |
| telemetry_app_ch2_current | Current measured by the device on channel 2 | Gauge | 🏷️ |
| telemetry_app_ch3_voltage | Voltage measured by the device on channel 3 | Gauge | 🏷️ |
| telemetry_app_ch3_current | Current measured by the device on channel 3 | Gauge | 🏷️ |
| telemetry_app_pm10_standard | Concentration Units Standard PM1.0 | Gauge | 🏷️ |
| telemetry_app_pm25_standard | Concentration Units Standard PM2.5 | Gauge | 🏷️ |
| telemetry_app_pm100_standard | Concentration Units Standard PM10.0 | Gauge | 🏷️ |
| telemetry_app_pm10_environmental | Concentration Units Environmental PM1.0 | Gauge | 🏷️ |
| telemetry_app_pm25_environmental | Concentration Units Environmental PM2.5 | Gauge | 🏷️ |
| telemetry_app_pm100_environmental | Concentration Units Environmental PM10.0 | Gauge | 🏷️ |
| telemetry_app_particles_03um | 0.3um Particle Count | Gauge | 🏷️ |
| telemetry_app_particles_05um | 0.5um Particle Count | Gauge | 🏷️ |
| telemetry_app_particles_10um | 1.0um Particle Count | Gauge | 🏷️ |
| telemetry_app_particles_25um | 2.5um Particle Count | Gauge | 🏷️ |
| telemetry_app_particles_50um | 5.0um Particle Count | Gauge | 🏷️ |
| telemetry_app_particles_100um | 10.0um Particle Count | Gauge | 🏷️ |
| telemetry_app_temperature | Temperature measured by the device | Gauge | 🏷️ |
| telemetry_app_relative_humidity | Relative humidity percent measured by the device | Gauge | 🏷️ |
| telemetry_app_barometric_pressure | Barometric pressure in hPA measured by the device | Gauge | 🏷️ |
| telemetry_app_gas_resistance | Gas resistance in MOhm measured by the device | Gauge | 🏷️ |
| telemetry_app_iaq | IAQ value measured by the device (0-500) | Gauge | 🏷️ |
| telemetry_app_distance | Distance measured by the device in mm | Gauge | 🏷️ |
| telemetry_app_lux | Ambient light measured by the device in Lux | Gauge | 🏷️ |
| telemetry_app_white_lux | White light measured by the device in Lux | Gauge | 🏷️ |
| telemetry_app_ir_lux | Infrared light measured by the device in Lux | Gauge | 🏷️ |
| telemetry_app_uv_lux | Ultraviolet light measured by the device in Lux | Gauge | 🏷️ |
| telemetry_app_wind_direction | Wind direction in degrees measured by the device | Gauge | 🏷️ |
| telemetry_app_wind_speed | Wind speed in m/s measured by the device | Gauge | 🏷️ |
| telemetry_app_weight | Weight in KG measured by the device | Gauge | 🏷️ |
| telemetry_app_battery_level | Battery level of the device (0-100, >100 means powered) | Gauge | 🏷️ |
| telemetry_app_voltage | Voltage measured by the device | Gauge | 🏷️ |
| telemetry_app_channel_utilization | Utilization for the current channel, including well-formed TX, RX, and noise | Gauge | 🏷️ |
| telemetry_app_air_util_tx | Percent of airtime for transmission used within the last hour | Gauge | 🏷️ |
| telemetry_app_uptime_seconds | How long the device has been running since the last reboot (in seconds) | Counter | 🏷️ |
| route_length | Number of nodes in the route | Counter | 🏷️ |
| route_response | Number of responses to route discovery | Counter | 🏷️, response_type |
| mesh_packet_source_types | Types of mesh packets processed by source | Counter | 🏷️ (source), portnum |
| mesh_packet_destination_types | Types of mesh packets processed by destination | Counter | 🏷️ (destination), portnum |
| mesh_packet_total | Total number of mesh packets processed | Counter | 🏷️ (source), 🏷️ (destination) |
| mesh_packet_rx_time | Receive time of mesh packets (seconds since 1970) | Histogram | 🏷️ (source), 🏷️ (destination) |
| mesh_packet_rx_snr | Receive SNR of mesh packets | Gauge | 🏷️ (source), 🏷️ (destination) |
| mesh_packet_hop_limit | Hop limit of mesh packets | Counter | 🏷️ (source), 🏷️ (destination) |
| mesh_packet_want_ack | Occurrences of want ACK for mesh packets | Counter | 🏷️ (source), 🏷️ (destination) |
| mesh_packet_via_mqtt | Occurrences of mesh packets sent via MQTT | Counter | 🏷️ (source), 🏷️ (destination) |
| mesh_packet_hop_start | Hop start of mesh packets | Gauge | 🏷️ (source), 🏷️ (destination) |
| mesh_packet_ids | Unique IDs for mesh packets | Counter | 🏷️ (source), 🏷️ (destination), packet_id |
| mesh_packet_channel | Channel used for mesh packets | Counter | 🏷️ (source), 🏷️ (destination), channel |
| mesh_packet_rx_rssi | Receive RSSI of mesh packets | Gauge | 🏷️ (source), 🏷️ (destination) |
2024-06-26 01:31:01 -07:00
## Configuration
The project uses a `.env` file for configuration. Here is an example of the configuration options available:
```dotenv
# Description: Environment variables for the application
2024-06-30 09:20:25 -07:00
# Postgres connection details
DATABASE_URL=postgres://postgres:postgres@postgres:5432/meshtastic
2024-06-26 01:31:01 -07:00
# Prometheus connection details
PROMETHEUS_COLLECTOR_PORT=9464
PROMETHEUS_JOB=example
# MQTT connection details
2024-06-28 04:21:01 -07:00
MQTT_HOST=
2024-06-26 01:31:01 -07:00
MQTT_PORT=1883
2024-06-28 04:21:01 -07:00
MQTT_USERNAME=
MQTT_PASSWORD=
2024-06-26 01:31:01 -07:00
MQTT_KEEPALIVE=60
MQTT_TOPIC='msh/israel/#'
MQTT_IS_TLS=false
# Exporter configuration
## Hide source data in the exporter (default: false)
MESH_HIDE_SOURCE_DATA=false
## Hide destination data in the exporter (default: false)
MESH_HIDE_DESTINATION_DATA=false
## Filtered ports in the exporter (default: 1, can be a comma-separated list of ports)
FILTERED_PORTS=0
## Hide message content in the TEXT_MESSAGE_APP packets (default: true) (Currently we only log message length, if we hide then all messages would have the same length)
HIDE_MESSAGE=false
2024-06-28 04:17:45 -07:00
## MQTT server Key for decoding messages
MQTT_SERVER_KEY=1PG7OiApB1nwvP+rz05pAQ==
2024-06-26 01:31:01 -07:00
```
## Running the Project
To run the project, simply use Docker Compose:
```bash
docker-compose up --build
```
2024-06-30 09:20:25 -07:00
This command will build and start all the necessary services, including the MQTT server, Prometheus server, Postgres
2024-06-26 01:31:01 -07:00
server, and Grafana.
## Grafana Dashboard
2024-06-30 09:20:25 -07:00
The project includes a Grafana dashboard pre-configured to connect to both the Prometheus and Postgres data sources.
This
2024-06-26 01:31:01 -07:00
allows you to start creating and customizing your dashboards right away.
## Contributing
2024-06-28 04:17:45 -07:00
Contributions are welcome! Please open an issue or submit a pull request on GitHub.
