96 lines
3.2 KiB
Markdown
96 lines
3.2 KiB
Markdown
# Shelly Exporter
|
|
|
|
Prometheus exporter for Shelly Gen1 Wi-Fi devices that expose monitoring data through the HTTP `/status` endpoint. It supports multiple devices, HTTP Basic Authentication, and dynamically exports only the capabilities present in each device response.
|
|
|
|
## Features
|
|
|
|
- Relays, inputs, rollers, lights, power meters, thermostats, and environmental or safety sensors.
|
|
- Correct Prometheus energy counters for both Gen1 `meters` and EM/3EM `emeters`.
|
|
- Concurrent collection from all configured devices.
|
|
- Per-device availability, request duration, and error metrics.
|
|
- Strict YAML validation, graceful shutdown, and a health endpoint.
|
|
- Generic `gen1` product type for compatible devices not explicitly listed.
|
|
|
|
## Quick start
|
|
|
|
Copy the example configuration and set the device address and credentials:
|
|
|
|
```sh
|
|
cp config.example.yaml config.yaml
|
|
```
|
|
|
|
```yaml
|
|
host: 0.0.0.0
|
|
port: 9090
|
|
logLevel: 4
|
|
|
|
shelly:
|
|
timeoutSeconds: 10
|
|
devices:
|
|
- name: office-plug
|
|
product: plug_s
|
|
url: http://192.168.0.30
|
|
username: admin
|
|
password: change-me
|
|
```
|
|
|
|
Build and start the exporter:
|
|
|
|
```sh
|
|
go test ./...
|
|
go build -o shelly-exporter .
|
|
./shelly-exporter -config config.yaml
|
|
```
|
|
|
|
The exporter exposes:
|
|
|
|
- Prometheus metrics at `http://localhost:9090/metrics`
|
|
- Process health at `http://localhost:9090/-/healthy`
|
|
|
|
## Supported products
|
|
|
|
| Family | Product identifiers |
|
|
| --- | --- |
|
|
| Generic Gen1 | `gen1` |
|
|
| Plugs | `plug`, `plug_s` |
|
|
| Relays and inputs | `shelly_1`, `shelly_1pm`, `shelly_1l`, `shelly_2`, `shelly_2_5`, `shelly_4pro`, `shelly_uni`, `shelly_i3`, `shelly_button1` |
|
|
| Energy meters | `shelly_em`, `shelly_3em` |
|
|
| Lights and dimmers | `shelly_bulb`, `shelly_bulb_rgbw`, `shelly_duo`, `shelly_vintage`, `shelly_rgbw2`, `shelly_dimmer` |
|
|
| Sensors and heating | `shelly_ht`, `shelly_flood`, `shelly_smoke`, `shelly_door_window`, `shelly_motion`, `shelly_sense`, `shelly_gas`, `shelly_trv` |
|
|
|
|
Product identifiers are case-insensitive and punctuation is normalized. For example, `Shelly 2.5` resolves to `shelly_2_5`, and `plug-s` resolves to `plug_s`.
|
|
|
|
## Documentation
|
|
|
|
- [Documentation index](docs/README.md)
|
|
- [Configuration reference](docs/configuration.md)
|
|
- [Metrics reference](docs/metrics.md)
|
|
- [Operations and troubleshooting](docs/operations.md)
|
|
- [Architecture and adding products](docs/architecture.md)
|
|
|
|
## Prometheus configuration
|
|
|
|
```yaml
|
|
scrape_configs:
|
|
- job_name: shelly
|
|
static_configs:
|
|
- targets: [shelly-exporter:9090]
|
|
```
|
|
|
|
Every device is contacted once during each Prometheus scrape. Choose a scrape interval appropriate for the device and network. Battery-powered Gen1 sensors normally sleep and may be reachable only briefly; push events or MQTT are generally better for continuous monitoring of those devices.
|
|
|
|
## Docker
|
|
|
|
```sh
|
|
docker build --rm -t shelly-exporter:latest .
|
|
docker run --rm -p 9090:9090 \
|
|
-v "$PWD/config.yaml:/opt/shelly-exporter/config.yaml:ro" \
|
|
shelly-exporter:latest
|
|
```
|
|
|
|
## Scope
|
|
|
|
This exporter currently implements the Shelly Gen1 `/status` protocol. Shelly Plus, Pro, Gen2, and Gen3 products use an RPC API and are not currently supported by this client.
|
|
|
|
Product fields and energy units follow the [official Shelly Gen1 API documentation](https://shelly-api-docs.shelly.cloud/gen1/).
|