shelly_device_exporter

README

Shelly Device Exporter

Prometheus exporter for Shelly Gen 2+ devices.

Features

Feature	Description
Concurrent Scraping	Dynamically-sized worker pool to fetch statuses from multiple devices simultaneously.
Authentication	Supports Shelly's required Digest Authentication out of the box.
Energy Cost Calculation	Automatically calculates ongoing energy costs based on configurable price_per_kwh and currency fields.

Device Compatibility

Compatible with all Gen 2+ devices utilizing the standard Shelly RPC API.

Device	Tested
Shelly Plug M Gen3	✅

Exported Metrics

See list of Metrics

Component	Status
Switch	✅
System	✅

Deployment

Usage

Usage: shelly_device_exporter [flags]

Prometheus exporter for Shelly Gen 2+ devices.

Flags:
  -h, --help                        Show context-sensitive help.
      --address=":8080"             The address where the server should listen on ($ADDRESS).
      --config-file="config.yml"    Configuration file path ($CONFIG_FILE)
      --log-format="console"        Set the output format of the logs. Must be "console" or "json" ($LOG_FORMAT).
      --log-level=INFO              Set the log level. Must be "DEBUG", "INFO", "WARN" or "ERROR" ($LOG_LEVEL).
      --log-add-source              Whether to add source file and line number to log records ($LOG_ADD_SOURCE).
      --version                     Print version information and exit

Configuration

The exporter requires a configuration file to know which devices to poll and how to connect to them.

---
# (Optional) Used to calculate the 'shelly_device_energy_cost_total' metric.
# Both fields must be set to enable cost calculation.
price_per_kwh: 0.10
currency: "EUR"

# List of Shelly devices to monitor
devices:
  - name: "home-servers"
    address: "http://SHELLY_DEVICE_IP"
    username: "admin" # Optional, defaults to "admin"
    password: "YOUR_PASSWORD"

Environment Variable Templating

The configuration file supports environment variable templating using the {{ env "VAR" }} syntax.

devices:
  - name: "home-servers"
    address: "http://192.168.0.6"
    username: "admin"
    password: '{{ env "SHELLY_DEVICE1_PASSWORD" }}'

Docker Compose

---
name: shelly-device-exporter
services:
  shelly-device-exporter:
    image: ghcr.io/veerendra2/shelly_device_exporter:latest
    container_name: shelly-device-exporter
    volumes:
      - ./config.yml:/config.yml
    environment:
      CONFIG_FILE: /config.yml
      SHELLY_DEVICE1_PASSWORD: ${SHELLY_DEVICE1_PASSWORD}
    restart: unless-stopped
    user: ${PUID}:${PGID}
    hostname: shelly-device-exporter

Prometheus Scrape Configuration

Add the following to your prometheus.yml scrape configurations to collect metrics from the exporter:

scrape_configs:
  - job_name: "shelly_devices"
    # Adjust scrape interval based on your needs
    scrape_interval: 30s
    scrape_timeout: 15s
    static_configs:
      - targets: ["shelly-device-exporter:8080"] # Replace with the exporter's address

Grafana Dashboard

• Download Grafana Dashbaord Json

Development

Build & Test

• Using Taskfile

Install Taskfile: Installation Guide

# Available tasks
task --list
task: Available tasks for this project:
* all:                   Run comprehensive checks: format, lint, security and test
* build:                 Build the application binary for the current platform
* build-docker:          Build Docker image
* build-platforms:       Build the application binaries for multiple platforms and architectures
* fmt:                   Formats all Go source files
* install:               Install required tools and dependencies
* lint:                  Run static analysis and code linting using golangci-lint
* run:                   Runs the main application
* security:              Run security vulnerability scan
* test:                  Runs all tests in the project      (aliases: tests)
* vet:                   Examines Go source code and reports suspicious constructs

• Build with goreleaser

Install GoReleaser: Installation Guide

# Build locally
goreleaser release --snapshot --clean

Shelly API Reference

• Authentication

For debugging purposes, you can directly access your Shelly devices via curl:

# Get device info
curl 'http://YOUR_SHELLY_IP/shelly'

# Get device status using Digest Auth
curl --digest -u admin:"YOUR_PASSWORD" 'http://YOUR_SHELLY_IP/rpc/Shelly.GetStatus'