opendtu-logger/README.md

# OpenDTU logger

OpenDTU logger connects to the OpenDTU livedata websocket and captures metrics.
These metrics are inserted into a PostgreSQL database.
Optionally, TimescaleDB can be used.

## Install instructions

Docker is the preferred way to install OpenDTU Logger, but using the binary is also possible.

### Docker

```sh
docker pull git.hollander.online/energy/opendtu-logger:0.0
```

Preferably, run the Docker image using the Docker compose examples provided in the `./docker` folder.

### Binary

Go to the [releases page](https://git.hollander.online/energy/opendtu-logger/releases) and download the most recent stable release.

#### Running the binary as local user

```sh
REMOTE_URL="opendtu:80" DB_URL="host=localhost port=5432 user=postgres password=secret dbname=dtu sslmode=disable" TIMESCALEDB_ENABLED="true" TZ="Europe/Amsterdam" ./opendtu-logger
```

#### Creating a more permanent setup on Linux using systemd

```sh
sudo adduser --system --group --disabled-login --home /opt/opendtu-logger opendtu-logger

sudo mkdir /opt/opendtu-logger
sudo mkdir /opt/opendtu-logger/data
sudo mv ./opendtu-logger /opt/opendtu-logger/

sudo chown -R opendtu-logger:opendtu-logger /opt/opendtu-logger
```

```sh
sudo nano /etc/systemd/system/opendtu-logger.service
```

Add the contents of `systemd/opendtu-logger.service` and alter the `REMOTE_URL` and `DB_URL` environment variables to match your setup.

### PostgreSQL setup

To install PostgreSQL on Debian / Ubuntu run

```sh
sudo apt install postgresql
```

The OpenDTU logger logs to a PostgreSQL database and optionally supports TimescaleDB. Create a separate database and user using the following commands.

```sql
CREATE DATABASE opendtu_logger;
CREATE USER opendtu_logger WITH password 'SECRET';
GRANT ALL privileges ON DATABASE opendtu_logger TO opendtu_logger;
GRANT ALL ON SCHEMA public TO opendtu_logger;
```

Optional: enable the TimescaleDB extension. To make use of TimescaleDB, follow the steps outlined in [their documentation](https://docs.timescale.com/self-hosted/latest/install/installation-linux/). Then, enable TimescaleDB support for the `opendtu_logger` database by executing the following commands

```sql
\c opendtu_logger
CREATE EXTENSION OF NOT EXISTS timescaledb;
```

## Environment variables

The following environment variables are required for OpenDTU Logger to be configured.

```conf
REMOTE_URL="opendtu:80"
DB_URL="host=localhost port=5432 user=postgres password=secret dbname=dtu sslmode=disable"
TIMESCALEDB_ENABLED="true"
TZ="Europe/Amsterdam"
```

- `REMOTE_URL`is used to specify the IP address or hostname OpenDTU is running on. E.g.: `192.168.1.6` or `opendtu.internal`
- `DB_URL` specifies the credentials required to connect to the PostgreSQL database. All [connection parameters documented by golang's `lib/pq` package](https://pkg.go.dev/github.com/lib/pq#hdr-Connection_String_Parameters) can be used.
- `TIMESCALEDB_ENABLED` should be set to `true` or `false`.
- `TZ` is used to ensure data is recorded with the right timestamp. Choose the timezone valid for your location from [this Wikipedia page](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).

## Grafana

The `grafana` folder contains example dashboards which can be imported into existing Grafana installs, or into the provided Docker Compose with Grafana setup.

- The `opendtu_` dashboards contain visualisations for each table the OpenDTU logger records to.
- `PV.json` is a dashboard which combines the visualisations of each table that I found to be most useful.
- `Zonnepanelen.json` is the same as `PV.json`, but in Dutch language.

## Known limitations

- The logger will currently log every event posted by OpenDTU to the websocket. Checks still need to be added to determine the uniqueness of an event. For more information, see also [this OpenDTU Github issue](https://github.com/tbnobody/OpenDTU/issues/1800).
- Upon restart of the OpenDTU, the OpenDTU Logger binary will need to be restarted as well. When using the provided `compose.yml` files with Docker, or using the `systemd` service file when using the binary, ensures this happens automatically.