mirror of
https://github.com/RWejlgaard/octopus_exporter.git
synced 2026-07-04 13:56:17 +00:00
135 lines
5.4 KiB
Markdown
135 lines
5.4 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 |
|
|
|
|
### Solar / export
|
|
|
|
Solar metrics are only exposed if an electricity export meter point (direction `EXPORT`) is found on the account. Solar export usually shares the physical meter and smart device with the import meter, so live export watts come from the same telemetry call as electricity demand (no extra API request).
|
|
|
|
| Metric | Source | Description |
|
|
|---|---|---|
|
|
| `octopus_solar_export_watts` | GraphQL | Live electricity export to the grid in watts |
|
|
| `octopus_solar_last_read_timestamp` | GraphQL | Unix timestamp of last solar export reading |
|
|
| `octopus_solar_export_kwh` | REST | Latest half-hourly energy exported to the grid in kWh |
|
|
| `octopus_solar_export_interval_timestamp` | REST | Unix timestamp of the start of the latest export interval |
|
|
| `octopus_solar_export_rate_pence` | GraphQL | Current export (outgoing) unit rate in pence per kWh |
|
|
|
|
### 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 |
|
|
| `OCTOPUS_SOLAR_MPAN` | No | Filter solar export meter by MPAN |
|
|
| `OCTOPUS_SOLAR_SERIAL` | No | Filter solar export meter by serial number |
|
|
| `OCTOPUS_SOLAR_DEVICE_ID` | No | Use a specific solar export 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`) |
|
|
| `LOG_LEVEL` | No | Minimum log level: `debug`, `info`, `warn`, `error` (default: `info`). Logs are emitted as JSON to stderr |
|
|
|
|
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 .
|
|
```
|