d1ceward/shellyplug-exporter repository overview

⁠shellyplug-exporter (v3.1.1)

Prometheus exporter for Shelly Plug S (Gen1) and Shelly Plus Plug S (Gen2), written in Crystal.

:rocket: Feature requests and suggestions are welcome, open an issue!

⁠Quick Start

⁠Step 1. Configure Your Plugs

Create a config.yaml to manage one or more plugs:

exporter_port: 5000
plugs:
  - name: plug1
    host: 192.168.33.2
    port: 80
    auth_username: user1
    auth_password: pass1
  - name: plug2
    host: 192.168.33.3
    port: 80
    auth_username: user2
    auth_password: pass2

⁠Step 2. Run exporter

⁠With docker

The container automatically loads /config.yaml if present, just mount your config file:

docker run -d \
  -p 8080:5000 \
  -v $(pwd)/config.yaml:/config.yaml \
  ghcr.io/d1ceward/shellyplug-exporter:latest

Or with docker-compose:

services:
  plug_exporter:
    image: ghcr.io/d1ceward/shellyplug-exporter:latest
    restart: unless-stopped
    ports:
      - 8080:5000
    volumes:
      - ./config.yaml:/config.yaml

⁠With binary

Using your config file:

shellyplug-exporter run --config config.yaml

⁠Legacy environment variables (Single Plug, Not recommended)

If you want to run with environment variables (for a single plug), you can use the following variables:

• SHELLYPLUG_HOST (required): IP address or hostname of the Shelly Plug S
• SHELLYPLUG_PORT (optional, default: 80): Port of the Shelly Plug S
• SHELLYPLUG_AUTH_USERNAME (optional): Username for HTTP Basic Auth
• SHELLYPLUG_AUTH_PASSWORD (optional): Password for HTTP Basic Auth
• EXPORTER_PORT (optional, default: 5000): Port for the exporter to listen on

Example with docker:

docker run -d \
  -p 8080:5000 \
  -e SHELLYPLUG_HOST="192.168.33.2" \
  -e SHELLYPLUG_PORT="80" \
  -e SHELLYPLUG_AUTH_USERNAME="user1" \
  -e SHELLYPLUG_AUTH_PASSWORD="pass1" \
  -e EXPORTER_PORT=5000 \
  ghcr.io/d1ceward/shellyplug-exporter:latest

⁠Metrics

Endpoint: /metrics

Multiple plugs: Every sample carries a name label, taken from the name field in the config file, or from the name configured on the plug itself when that field is left empty:

# HELP shellyplug_power Current power drawn in watts
# TYPE shellyplug_power gauge
shellyplug_power{name="plug1"} 12.3
shellyplug_power{name="plug2"} 8.7

⁠Contributing

Bug reports and pull requests are welcome! By contributing, you agree to the Code of Merit.

1. Fork: github.com/d1ceward/shellyplug-exporter⁠
2. Create a branch: git checkout -b my-new-feature
3. Commit: git commit -am 'Add some feature'
4. Push: git push origin my-new-feature
5. Open a Pull Request

⁠Development

1. Install Crystal (see .tool-versions)
2. Install dependencies: shards install
3. Build: shards build
4. Binary: bin/shellyplug-exporter

Run tests:

crystal spec

⁠Documentation

See: d1ceward.github.io/shellyplug-exporter⁠

⁠Contributors

• d1ceward⁠ – creator and maintainer