mirror of
https://github.com/RWejlgaard/octopus_exporter.git
synced 2026-07-04 13:56:17 +00:00
119 lines
4.1 KiB
Markdown
119 lines
4.1 KiB
Markdown
# octopus_exporter
|
|
|
|
A Prometheus exporter for Octopus Energy smart meter data, using the Kraken GraphQL API.
|
|
|
|
## Metrics
|
|
|
|
### Electricity
|
|
|
|
| Metric | Source | Description |
|
|
|---|---|---|
|
|
| `octopus_electricity_demand_watts` | GraphQL | Live electricity demand in watts |
|
|
| `octopus_electricity_last_read_timestamp` | GraphQL | Unix timestamp of last electricity reading |
|
|
| `octopus_electricity_consumption_kwh` | REST | Latest half-hourly consumption in kWh |
|
|
| `octopus_electricity_consumption_interval_timestamp` | REST | Unix timestamp of the start of the latest consumption interval |
|
|
| `octopus_electricity_unit_rate_pence` | GraphQL / REST | Current unit rate in pence per kWh (Agile customers get the live half-hourly rate from the REST API) |
|
|
| `octopus_electricity_standing_charge_pence` | GraphQL | Current standing charge in pence per day |
|
|
|
|
### Gas
|
|
|
|
Gas metrics are only exposed if a smart gas meter is found on the account.
|
|
|
|
| Metric | Source | Description |
|
|
|---|---|---|
|
|
| `octopus_gas_demand_watts` | GraphQL | Live gas demand in watts |
|
|
| `octopus_gas_last_read_timestamp` | GraphQL | Unix timestamp of last gas reading |
|
|
| `octopus_gas_consumption_kwh` | REST | Latest half-hourly consumption in kWh |
|
|
| `octopus_gas_consumption_interval_timestamp` | REST | Unix timestamp of the start of the latest gas consumption interval |
|
|
| `octopus_gas_unit_rate_pence` | GraphQL | Current unit rate in pence per kWh |
|
|
| `octopus_gas_standing_charge_pence` | GraphQL | Current standing charge in pence per day |
|
|
|
|
### Account
|
|
|
|
| Metric | Source | Description |
|
|
|---|---|---|
|
|
| `octopus_account_balance_pence` | GraphQL | Account balance in pence (positive = credit, negative = debit) |
|
|
|
|
### Exporter health
|
|
|
|
| Metric | Description |
|
|
|---|---|
|
|
| `octopus_up` | 1 if the last poll cycle completed without errors, 0 otherwise |
|
|
| `octopus_last_poll_timestamp` | Unix timestamp of the last completed poll cycle |
|
|
| `octopus_poll_errors_total` | Total number of collector errors across all poll cycles |
|
|
| `octopus_token_refreshes_total` | Total number of successful JWT token refreshes |
|
|
| `octopus_rate_limit_retries_total` | Total number of 429 rate-limit retries |
|
|
| `octopus_build_info{version,commit}` | Build metadata (always 1) |
|
|
|
|
Metrics are refreshed every `POLL_INTERVAL` (default 60 seconds).
|
|
|
|
## Configuration
|
|
|
|
| Variable | Required | Description |
|
|
|---|---|---|
|
|
| `OCTOPUS_API_KEY` | Yes | Your Octopus Energy API key |
|
|
| `OCTOPUS_MPAN` | No | Filter electricity meter by MPAN |
|
|
| `OCTOPUS_SERIAL` | No | Filter electricity meter by serial number |
|
|
| `OCTOPUS_DEVICE_ID` | No | Use a specific electricity smart device ID directly |
|
|
| `OCTOPUS_GAS_MPRN` | No | Filter gas meter by MPRN |
|
|
| `OCTOPUS_GAS_SERIAL` | No | Filter gas meter by serial number |
|
|
| `OCTOPUS_GAS_DEVICE_ID` | No | Use a specific gas smart device ID directly |
|
|
| `PORT` | No | Port to expose metrics on (default: `9359`) |
|
|
| `POLL_INTERVAL` | No | How often to poll Octopus APIs (Go duration, default: `60s`) |
|
|
|
|
If no filter variables are set, the exporter auto-discovers the first smart meter of each type found on the account. Use `OCTOPUS_MPAN` / `OCTOPUS_MPRN` to pin to a specific meter on accounts with multiple meters.
|
|
|
|
Your API key can be found in the [Octopus Energy developer dashboard](https://octopus.energy/dashboard/new/accounts/personal-details/api-access).
|
|
|
|
## Docker
|
|
|
|
```sh
|
|
docker run -d \
|
|
-e OCTOPUS_API_KEY=sk_live_... \
|
|
-e OCTOPUS_MPAN=1234567890123 \
|
|
-p 9359:9359 \
|
|
rwejlgaard/octopus_exporter
|
|
```
|
|
|
|
## Docker Compose
|
|
|
|
```yaml
|
|
services:
|
|
octopus-exporter:
|
|
image: rwejlgaard/octopus_exporter:latest
|
|
restart: unless-stopped
|
|
environment:
|
|
OCTOPUS_API_KEY: sk_live_...
|
|
OCTOPUS_MPAN: "1234567890123" # optional, auto-discovered if omitted
|
|
ports:
|
|
- "9359:9359"
|
|
```
|
|
|
|
## Running from source
|
|
|
|
Requires Go 1.24+.
|
|
|
|
```sh
|
|
git clone https://github.com/rwejlgaard/octopus_exporter
|
|
cd octopus_exporter
|
|
OCTOPUS_API_KEY=sk_live_... go run ./cmd/octopus_exporter
|
|
```
|
|
|
|
## Prometheus configuration
|
|
|
|
```yaml
|
|
scrape_configs:
|
|
- job_name: octopus
|
|
static_configs:
|
|
- targets: ['localhost:9359']
|
|
```
|
|
|
|
## Building
|
|
|
|
```sh
|
|
go build ./cmd/octopus_exporter
|
|
```
|
|
|
|
```sh
|
|
docker build -t rwejlgaard/octopus_exporter .
|
|
```
|