# 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`. |