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:
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. |
