214 lines
7.7 KiB
Markdown
214 lines
7.7 KiB
Markdown
# 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.
|
|
|