HAddons/loki/DOCS.md

# Home Assistant Add-on: Loki

## Install

First add the repository to the add-on store (`https://mezgit.duckdns.org/mezned/HAddons`):

[![Open your Home Assistant instance and show the add add-on repository dialog
with a specific repository URL pre-filled.][add-repo-shield]][add-repo]

Then find Loki in the store and click install:

[![Open your Home Assistant instance and show the dashboard of a Supervisor add-on.][add-addon-shield]][add-addon]

## Default Setup

If you are also using the Promtail add-on in this repository then by default
Promtail wil ship Loki the systemd journal of the host. That will include all
logs from all addons, supervisor, home assistant, docker, and the host system
itself. No additional configuration is required if that's the setup you want.

The configuration options can be used to encrypt traffic to Loki via SSL or
limit access via mTLS. If you change those though, make sure to update your
Promtail (or whatever client your using) config accordingly.

Additionally, if you are an expert and want to take full control over Loki's
configuration there's an option to provide a custom config file.

## Configuration

**Note**: _Remember to restart the add-on when the configuration is changed._

Example add-on configuration:

```yaml
ssl: true
certfile: fullchain.pem
keyfile: privkey.pem
days_to_keep: 30
log_level: info
```

**Note**: _This is just an example, don't copy and paste it! Create your own!_

### Option: `ssl`

Enables/Disables SSL (HTTPS). Set it `true` to enable it, `false` otherwise.

### Option: `certfile`

The certificate file to use for SSL.

**Note**: _The file MUST be stored in `/ssl/`, which is the default_

### Option: `keyfile`

The private key file to use for SSL.

**Note**: _The file MUST be stored in `/ssl/`, which is the default_

### Option: `cafile`

The CA certificate file used to sign client certificates. If set,cclients will
be required to present a valid client-authentication certificate to connect to
Loki (mTLS).

**Note**: _The file MUST be stored in `/ssl/`, which is the default_

### Option: `days_to_keep`

Number of days of logs to keep, older logs will be purged from the index. If set,
minimum is `1`, defaults to `30` if omitted.

The minimum exists because `0` tells Loki to keep tables indefinitely (and the
addon to grow without bound). See [retention][loki-doc-retention] for more information
on how Loki's Compactor handles retention.

**Note**: This sets an environmental variable referenced in the [default config][addon-default-config].
If you use `config_path` below it is ignored unless you reference the same variable.

### Option: `config_path`

Absolute path to a custom config file for Loki. By default this addon will run
Loki using the config file [here][addon-default-config]. If you would prefer different
options then you can create your own config file to use instead and provide the
path to it.

Review the [documentation][loki-doc] to learn about creating a config file for
Loki. You can also see examples [here][loki-doc-examples]. I would also strongly
recommend reading the [Loki best practices][loki-doc-best-practices] guide before
proceeding with a custom config.

**Note**: `http_listen_address`, `http_listen_port` and `log_level` are set by
the add-on via CLI params so they cannot be changed. Everything else can be configured
in your file.

### Option: `log_level`

The `log_level` option controls the level of log output by the addon and can
be changed to be more or less verbose, which might be useful when you are
dealing with an unknown issue. Possible values are:

- `debug`: Shows detailed debug information.
- `info`: Normal (usually) interesting events.
- `warning`: Exceptional occurrences that are not errors.
- `error`: Runtime errors that do not require immediate action.

Please note that each level automatically includes log messages from a
more severe level, e.g., `debug` also shows `info` messages. By default,
the `log_level` is set to `info`, which is the recommended setting unless
you are troubleshooting.

### Port: `3100/tcp`

This is the port that Loki is listening on and that clients such as Promtail
should point at.

**Note**: If you just want to send logs from the Promtail add-on to this one
you can leave this disabled. Setting it exposes the port on the host so you
only need to do that if you want other systems to ship logs to Loki.

## PLG Stack (Promtail, Loki and Grafana)

Loki isn't a standalone application, it doesn't do anything until you set up another
utility to send logs to it. It's job is to receive logs, index them, and make them
available to analysis tools such as Grafana. Loki typically expects to be deployed
in the full PLG stack:

- Promtail to process and ship logs
- Loki to aggregate and index them
- Grafana to visualize and monitor them

### Promtail

Promtail is also made by Grafana, its only job is to scrape logs and send them
to Loki. The easiest way to get it set up is to install the
Promtail add-on in this same repository.

[![Open your Home Assistant instance and show the dashboard of a Supervisor add-on.][add-addon-shield]][add-addon-promtail]

This isn't the only way to get logs into Loki though. You may want to deploy
Promtail yourself to ship logs from other systems, you can find installation
instructions for that [here][promtail-doc-installation].

Other clients besides Promtail can also be configured to ship their logs to
Loki. The list of supported clients and how to set them up can be found [here][loki-doc-clients]

### Grafana

Grafana's flagship product is their [analysis and visualization tool][grafana]
and it is very easy to connect that to Loki (as you'd likely expect). They have
a guide on how to connect the two [here][loki-in-grafana].

The easiest way to install Grafana is to use the
Grafana community add-on. From there you can follow the guide above to add Loki
as a data source. When prompted for Loki's URL in the Grafana add-on, use `http://39bd2704-loki:3100`
(or `https://39bd2704-loki:3100` if you enabled SSL).

[![Open your Home Assistant instance and show the dashboard of a Supervisor add-on.][add-addon-shield]][add-addon-grafana]

### LogCLI

Not required, but if you want to be able to interface with Loki via the
commandline for testing or scripting purposes you can set up [LogCLI][logcli].
This will then let you query Loki using [LogQL][logql].

To make LogCLI accessible in the SSH add-ons you can set this install script
to run on startup of the add-on:

```bash
#!/bin/bash

# Set up LogCLI (not available in alpine linux)
# On 2.1.0 (see https://github.com/grafana/loki/releases )
VERSION=2.1.0

APKARCH="$(apk --print-arch)"
case "$APKARCH" in
  x86_64)  BINARCH='amd64' ;;
  armhf)   BINARCH='arm' ;;
  armv7)   BINARCH='arm' ;;
  aarch64) BINARCH='arm64' ;;
  *) echo >&2 "error: unsupported architecture ($APKARCH)"; exit 1 ;;
esac

curl -J -L -o /tmp/logcli.zip "https://github.com/grafana/loki/releases/download/v${VERSION}/logcli-linux-${BINARCH}.zip"
unzip /tmp/logcli.zip -d /usr/bin
mv "/usr/bin/logcli-linux-${BINARCH}" /usr/bin/logcli
chmod a+x /usr/bin/logcli
rm -f /tmp/logcli.zip
```

You also need to add the following to your `.bash_profile` or `.zshrc` file:

```bash
export LOKI_ADDR=http://39bd2704-loki:3100
```

Switch to `https` if you enabled SSL. The LogCLI doc has the full list of
possible exports you may need depending on how you deployed Loki.

## Changelog & Releases

This repository keeps a change log using [GitHub's releases][releases]
functionality.

Releases are based on [Semantic Versioning][semver], and use the format
of `MAJOR.MINOR.PATCH`. In a nutshell, the version will be incremented
based on the following:

- `MAJOR`: Incompatible or major changes.
- `MINOR`: Backwards-compatible new features and enhancements.
- `PATCH`: Backwards-compatible bugfixes and package updates.