189 lines
12 KiB
Markdown
189 lines
12 KiB
Markdown
# Metrics reference
|
|
|
|
Shelly Exporter exposes OpenMetrics-compatible Prometheus data on `/metrics`. A collection starts when Prometheus requests that endpoint; the exporter does not poll devices in the background.
|
|
|
|
## Conventions
|
|
|
|
- Every series has a stable `device` label taken from configuration.
|
|
- Request health metrics also have a normalized `product` label.
|
|
- Channel-based values use a zero-based `index` label matching the position in the Shelly JSON array.
|
|
- Information metrics have a constant value of `1` and place textual state in labels.
|
|
- Boolean gauges use `1` for true or active and `0` for false or inactive.
|
|
- A metric is omitted when its source field is absent. Missing metrics do not imply a zero value.
|
|
- Device credentials and URLs are not exported as labels.
|
|
|
|
## Exporter and device health
|
|
|
|
These metrics exist for every configured device, including failed scrapes.
|
|
|
|
| Metric | Type | Labels | Description |
|
|
| --- | --- | --- | --- |
|
|
| `shelly_up` | gauge | `device`, `product` | `1` when the latest `/status` request and JSON decoding succeeded; otherwise `0`. |
|
|
| `shelly_scrape_duration_seconds` | gauge | `device`, `product` | Wall-clock duration of the latest device request. |
|
|
| `shelly_scrape_errors_total` | counter | `device`, `product` | Failed requests since this exporter process started. |
|
|
|
|
On a failed request only these three metric families are emitted for the affected device. A failure from one device does not prevent concurrent devices from being collected.
|
|
|
|
## Common Gen1 status
|
|
|
|
| Metric | Type | Additional labels | Description |
|
|
| --- | --- | --- | --- |
|
|
| `shelly_device_info` | gauge | `product`, `mac`, `firmware` | Configured product and device identity. Value is always `1`. |
|
|
| `shelly_wifi_info` | gauge | `ssid`, `ip` | Connected Wi-Fi network identity. Value is always `1`. |
|
|
| `shelly_wifi_connected` | gauge | none | Wi-Fi station connection state. |
|
|
| `shelly_wifi_rssi_dbm` | gauge | none | Received Wi-Fi signal strength in dBm. |
|
|
| `shelly_cloud_enabled` | gauge | none | Shelly Cloud enabled state. |
|
|
| `shelly_cloud_connected` | gauge | none | Shelly Cloud connection state. |
|
|
| `shelly_mqtt_connected` | gauge | none | MQTT connection state. |
|
|
| `shelly_update_available` | gauge | none | Firmware update availability. |
|
|
| `shelly_update_info` | gauge | `status`, `current_version`, `new_version` | Firmware update state. Value is always `1`. |
|
|
| `shelly_status_serial` | gauge | none | Device status sequence number. |
|
|
| `shelly_ram_size_bytes` | gauge | none | Total device RAM. |
|
|
| `shelly_ram_free_bytes` | gauge | none | Available device RAM. |
|
|
| `shelly_filesystem_size_bytes` | gauge | none | Total filesystem size. |
|
|
| `shelly_filesystem_free_bytes` | gauge | none | Free filesystem space. |
|
|
| `shelly_filesystem_mounted` | gauge | none | Data filesystem mount state, reported by products such as 3EM. |
|
|
| `shelly_uptime_seconds` | gauge | none | Device uptime. |
|
|
|
|
## Relays and inputs
|
|
|
|
| Metric | Type | Additional labels | Description |
|
|
| --- | --- | --- | --- |
|
|
| `shelly_relay_on` | gauge | `index` | Relay output state. |
|
|
| `shelly_relay_has_timer` | gauge | `index` | Whether a relay timer is active. |
|
|
| `shelly_relay_timer_duration_seconds` | gauge | `index` | Configured duration of the relay timer. |
|
|
| `shelly_relay_timer_remaining_seconds` | gauge | `index` | Remaining relay timer duration. |
|
|
| `shelly_relay_overpower` | gauge | `index` | Relay overpower protection state. |
|
|
| `shelly_relay_valid` | gauge | `index` | Relay status validity when provided by the device. |
|
|
| `shelly_input_on` | gauge | `index` | Logical input state. |
|
|
| `shelly_input_event_info` | gauge | `index`, `event`, `last_sequence` | Latest button/input event. Value is always `1`. |
|
|
| `shelly_input_event_count_total` | counter | `index` | Input events since device restart. A reboot is interpreted by Prometheus as a counter reset. |
|
|
|
|
## Standard power meters
|
|
|
|
The `meters` block is used by Plug, Plug S, PM relays, dimmers, and several light products.
|
|
|
|
| Metric | Type | Additional labels | Description |
|
|
| --- | --- | --- | --- |
|
|
| `shelly_meter_power_watts` | gauge | `index` | Current active power. |
|
|
| `shelly_meter_valid` | gauge | `index` | Meter reading validity. |
|
|
| `shelly_meter_timestamp_seconds` | gauge | `index` | Unix timestamp of the latest counter reading. |
|
|
| `shelly_meter_overpower` | gauge | `index` | Boolean overpower state on products that return a boolean. |
|
|
| `shelly_meter_overpower_threshold_watts` | gauge | `index` | Overpower threshold on products that return a numeric value. |
|
|
| `shelly_meter_recent_energy_watt_minutes` | gauge | `index`, `minute` | Device-provided recent per-minute energy slots. `minute` is the zero-based array position. |
|
|
| `shelly_meter_energy_watt_hours_total` | counter | `index` | Cumulative consumed energy converted from watt-minutes to watt-hours. |
|
|
|
|
Shelly reports `meters[].total` in watt-minutes. The exporter divides the value by 60:
|
|
|
|
```text
|
|
shelly_meter_energy_watt_hours_total = meters[index].total / 60
|
|
```
|
|
|
|
For example, a device total of `4188430` watt-minutes is exported as approximately `69807.1667` Wh.
|
|
|
|
## EM and 3EM power meters
|
|
|
|
The `emeters` block uses watt-hours directly and can include returned energy.
|
|
|
|
| Metric | Type | Additional labels | Description |
|
|
| --- | --- | --- | --- |
|
|
| `shelly_emeter_power_watts` | gauge | `index` | Current active power. |
|
|
| `shelly_emeter_reactive_power_var` | gauge | `index` | Current reactive power. |
|
|
| `shelly_emeter_power_factor` | gauge | `index` | Power factor, primarily on 3EM. |
|
|
| `shelly_emeter_current_amperes` | gauge | `index` | Measured current, primarily on 3EM. |
|
|
| `shelly_emeter_voltage_volts` | gauge | `index` | RMS voltage. |
|
|
| `shelly_emeter_valid` | gauge | `index` | Energy meter validity. |
|
|
| `shelly_emeter_energy_watt_hours_total` | counter | `index` | Cumulative consumed energy in Wh. No conversion is applied. |
|
|
| `shelly_emeter_returned_energy_watt_hours_total` | counter | `index` | Cumulative energy returned to the grid in Wh. |
|
|
| `shelly_total_power_watts` | gauge | none | Sum of power over all channels when supplied by the device. |
|
|
|
|
The device can reset persisted totals through its API. Prometheus correctly treats a decrease as a counter reset when functions such as `rate()` or `increase()` are used.
|
|
|
|
## Rollers
|
|
|
|
| Metric | Type | Additional labels | Description |
|
|
| --- | --- | --- | --- |
|
|
| `shelly_roller_info` | gauge | `index`, `state`, `stop_reason`, `last_direction` | Roller textual state. Value is always `1`. |
|
|
| `shelly_roller_power_watts` | gauge | `index` | Current motor power. |
|
|
| `shelly_roller_valid` | gauge | `index` | Power meter validity. |
|
|
| `shelly_roller_safety_switch` | gauge | `index` | Safety input state. |
|
|
| `shelly_roller_overtemperature` | gauge | `index` | Roller overtemperature state. |
|
|
| `shelly_roller_position_percent` | gauge | `index` | Current position in percent. A device may use a negative value for an invalid or uncalibrated position. |
|
|
| `shelly_roller_calibrating` | gauge | `index` | Calibration in progress. |
|
|
| `shelly_roller_positioning` | gauge | `index` | Position control availability. |
|
|
|
|
## Lights and dimmers
|
|
|
|
| Metric | Type | Additional labels | Description |
|
|
| --- | --- | --- | --- |
|
|
| `shelly_light_info` | gauge | `index`, `mode` | Light operating mode. Value is always `1`. |
|
|
| `shelly_light_on` | gauge | `index` | Light output state. |
|
|
| `shelly_light_has_timer` | gauge | `index` | Light timer state. |
|
|
| `shelly_light_timer_remaining_seconds` | gauge | `index` | Remaining light timer duration. |
|
|
| `shelly_light_brightness_percent` | gauge | `index` | Brightness in percent. |
|
|
| `shelly_light_red` | gauge | `index` | Red channel, normally `0..255`. |
|
|
| `shelly_light_green` | gauge | `index` | Green channel, normally `0..255`. |
|
|
| `shelly_light_blue` | gauge | `index` | Blue channel, normally `0..255`. |
|
|
| `shelly_light_white` | gauge | `index` | White channel, normally `0..255`. |
|
|
| `shelly_light_gain_percent` | gauge | `index` | Color gain in percent. |
|
|
| `shelly_light_color_temperature_kelvin` | gauge | `index` | White color temperature. |
|
|
| `shelly_light_effect` | gauge | `index` | Selected numeric effect. |
|
|
|
|
## Environmental and safety sensors
|
|
|
|
| Metric | Type | Additional labels | Description |
|
|
| --- | --- | --- | --- |
|
|
| `shelly_temperature_celsius` | gauge | none | Internal or primary sensor temperature in °C. |
|
|
| `shelly_temperature_valid` | gauge | none | Temperature reading validity. |
|
|
| `shelly_temperature_status_info` | gauge | `status` | Textual temperature state such as `Normal`. Value is always `1`. |
|
|
| `shelly_overtemperature` | gauge | none | Device overtemperature protection state. |
|
|
| `shelly_humidity_percent` | gauge | none | Relative humidity. |
|
|
| `shelly_humidity_valid` | gauge | none | Humidity reading validity. |
|
|
| `shelly_battery_percent` | gauge | none | Estimated battery capacity. |
|
|
| `shelly_battery_voltage_volts` | gauge | none | Measured battery voltage. |
|
|
| `shelly_charger_connected` | gauge | none | External charger state. |
|
|
| `shelly_illuminance_lux` | gauge | none | Measured illuminance. |
|
|
| `shelly_illuminance_valid` | gauge | none | Illuminance reading validity. |
|
|
| `shelly_illuminance_info` | gauge | `illumination` | Classified illumination such as `dark`, `twilight`, or `bright`. |
|
|
| `shelly_sensor_valid` | gauge | none | Primary product sensor validity. |
|
|
| `shelly_sensor_error` | gauge | none | Product-specific sensor error code. |
|
|
| `shelly_connect_retries` | gauge | none | Wi-Fi retries during the current wake cycle. |
|
|
| `shelly_motion` | gauge | none | Motion detection state. |
|
|
| `shelly_motion_active` | gauge | none | Motion detection enabled/active state. |
|
|
| `shelly_motion_timestamp_seconds` | gauge | none | Motion reading Unix timestamp. |
|
|
| `shelly_vibration` | gauge | none | Motion sensor vibration/tamper state. |
|
|
| `shelly_smoke` | gauge | none | Smoke detection state. |
|
|
| `shelly_flood` | gauge | none | Flood detection state. |
|
|
| `shelly_rain_sensor_mode` | gauge | none | Flood sensor rain mode. |
|
|
| `shelly_door_window_info` | gauge | `state` | Door/window state, normally `open` or `close`. Value is always `1`. |
|
|
| `shelly_tilt_degrees` | gauge | none | Door/window tilt. |
|
|
| `shelly_vibration_value` | gauge | none | Raw door/window vibration state; `-1` can mean disabled. |
|
|
| `shelly_vibration_time_seconds` | gauge | none | Door/window vibration validity duration. |
|
|
| `shelly_adc_voltage_volts` | gauge | `index` | Shelly Uni ADC voltage. |
|
|
| `shelly_external_temperature_celsius` | gauge | `index`, `hardware_id` | External addon temperature. |
|
|
| `shelly_external_humidity_percent` | gauge | `index`, `hardware_id` | External addon humidity. |
|
|
|
|
## Shelly TRV
|
|
|
|
| Metric | Type | Additional labels | Description |
|
|
| --- | --- | --- | --- |
|
|
| `shelly_thermostat_valve_position_percent` | gauge | `index` | Valve position. A negative value can mean uncalibrated. |
|
|
| `shelly_thermostat_target_enabled` | gauge | `index` | Automatic target control state. |
|
|
| `shelly_thermostat_target_temperature_celsius` | gauge | `index` | Target temperature when reported in °C. |
|
|
| `shelly_thermostat_temperature_celsius` | gauge | `index` | Measured thermostat temperature. |
|
|
| `shelly_thermostat_temperature_valid` | gauge | `index` | Thermostat temperature validity. |
|
|
| `shelly_thermostat_schedule_enabled` | gauge | `index` | Schedule state. |
|
|
| `shelly_thermostat_schedule_profile` | gauge | `index` | Selected schedule profile. |
|
|
| `shelly_thermostat_boost_minutes` | gauge | `index` | Boost duration in minutes. |
|
|
| `shelly_thermostat_window_open` | gauge | `index` | Open-window state. |
|
|
| `shelly_thermostat_calibrated` | gauge | none | Valve calibration state. |
|
|
|
|
## Shelly Gas
|
|
|
|
| Metric | Type | Additional labels | Description |
|
|
| --- | --- | --- | --- |
|
|
| `shelly_gas_concentration_ppm` | gauge | none | Combustible gas concentration in ppm. |
|
|
| `shelly_gas_concentration_valid` | gauge | none | Concentration reading validity. |
|
|
| `shelly_gas_sensor_info` | gauge | `sensor_state`, `self_test_state`, `alarm_state` | Sensor operating and alarm state. Value is always `1`. |
|
|
| `shelly_gas_valve_info` | gauge | `index`, `state` | Valve addon state. Value is always `1`. |
|