<a id="history-logging"></a>

# History logging

To enable history logging there are some steps that need to be completed which are outlined below.

<a id="install-elasticsearch"></a>

## Install Elasticsearch

Elastic has an article on installing Elasticsearch [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html).

<a id="import-an-index-template"></a>

## Import an index template

Import one of the index templates below ([Delivery attempts]() **or** [Transactions]()) into Elasticsearch. The differences between these index templates are described in each section.

<a id="history-delivery-attempts"></a>

<a id="delivery-attempts"></a>

### Delivery attempts

This template will log all delivery attempts and the same message may appear multiple times, once for each delivery attempt.
For this template you should set the value for `elasticsearch.index` to `halon-delivery-attempts` in the `web.yaml` file.

> ```console
> curl -k -X PUT -H "Content-Type: application/json" -d @/opt/halon/web/share/history/elasticsearch/delivery-attempts/halon_timeseries_policy.json http://elastic:elastic@127.0.0.1:9200/_ilm/policy/halon-timeseries-policy
> curl -k -X PUT -H "Content-Type: application/json" -d @/opt/halon/web/share/history/elasticsearch/delivery-attempts/halon_delivery_attempts.json http://elastic:elastic@127.0.0.1:9200/_index_template/halon-delivery-attempts
> ```

<a id="transactions"></a>

### Transactions

This template will log all transactions and update the state for them instead of creating a new log entry after each delivery attempt.
For this template you should set the value for `elasticsearch.index` to `halon-transactions-*` in the `web.yaml` file.

> ```console
> curl -k -X PUT -H "Content-Type: application/json" -d @/opt/halon/web/share/history/elasticsearch/transactions/halon_transactions_policy.json http://elastic:elastic@127.0.0.1:9200/_ilm/policy/halon-transactions-policy
> curl -k -X PUT -H "Content-Type: application/json" -d @/opt/halon/web/share/history/elasticsearch/transactions/halon_transactions.json http://elastic:elastic@127.0.0.1:9200/_index_template/halon-transactions
> ```

<a id="add-configuration"></a>

## Add configuration

The [history feature](history.html.md) **requires** an additional configuration file.
This configuration file is used to define fields in Elasticsearch and how they should be rendered.

*halon-web* loads the non-reloadable configuration from `/etc/halon/web-history.yaml`.
It is described by, and can be validated with, the [web-history.schema.json](http://lbovet.github.io/docson/index.html#https://docs.halon.io/json-schemas/web/1.32-stable/web-history.schema.json) JSON schema.
The default startup configuration file in `/opt/halon/web/share` can normally be used as a base (only choose one of them):

The following configuration is based on the Elasticsearch index template called **halon-delivery-attempts**:

```console
# cp /opt/halon/web/share/history/delivery-attempts.yaml /etc/halon/web-history.yaml
```

The following configuration is based on the Elasticsearch index template called **halon-transactions**:

```console
# cp /opt/halon/web/share/history/transactions.yaml /etc/halon/web-history.yaml
```

Use the [`elasticsearch`](config.html.md#confval-elasticsearch) directives to enable history logging in the web administration.
Sample *web.yaml* config using the [Delivery attempts]() template:

```yaml
elasticsearch:
  index: 'halon-delivery-attempts'
  nodes:
    - url: http://127.0.0.1:9200
  auth:
    username: elastic
    password: elastic
  tls:
    rejectUnauthorized: false
```

<a id="history-datamasking"></a>

## History datamasking

To hide history source paths and disallow them in queries for specific users or groups, use
[`users[].features.datamasking.history`](config.html.md#confval-users-.features.datamasking.history) or [`groups[].features.datamasking.history`](config.html.md#confval-groups-.features.datamasking.history).

<a id="start-sending-data"></a>

## Start sending data

To start sending data to Elasticsearch from the *smtpd* process using [HSL](https://docs.halon.io/hsl/) you can use the [history-elastic](https://github.com/halon-extras/history-elastic) plugin (supports both index templates).
