6 Elasticsearch setup

Elasticsearch support is experimental!

Zabbix supports the storage of historical data by means of Elasticsearch instead of a database. Users can choose the storage place for historical data between a compatible database and Elasticsearch. The setup procedure described in this section is applicable to Elasticsearch version 7.X. In case an earlier or later version of Elasticsearch is used, some functionality may not work as intended.

If all history data is stored in Elasticsearch, trends are not calculated nor stored in the database. With no trends calculated and stored, the history storage period may need to be extended.

Configuration

To ensure proper communication between all elements involved make sure server configuration file and frontend configuration file parameters are properly configured.

Zabbix server and frontend

Zabbix server configuration file draft with parameters to be updated:

  1. ### Option: HistoryStorageURL
  2.        # History storage HTTP[S] URL.
  3.        #
  4.        # Mandatory: no
  5.        # Default:
  6.        # HistoryStorageURL= 
  7.        ### Option: HistoryStorageTypes
  8.        # Comma separated list of value types to be sent to the history storage.
  9.        #
  10.        # Mandatory: no
  11.        # Default:
  12.        # HistoryStorageTypes=uint,dbl,str,log,text

Example parameter values to fill the Zabbix server configuration file with:

  1. HistoryStorageURL=http://test.elasticsearch.lan:9200
  2.        HistoryStorageTypes=str,log,text

This configuration forces Zabbix Server to store history values of numeric types in the corresponding database and textual history data in Elasticsearch.

Elasticsearch supports the following item types:

  1. uint,dbl,str,log,text

Supported item type explanation:

Item value typeDatabase tableElasticsearch type
Numeric (unsigned)history_uintuint
Numeric (float)historydbl
Characterhistory_strstr
Loghistory_loglog
Texthistory_texttext

Zabbix frontend configuration file (conf/zabbix.conf.php) draft with parameters to be updated:

  1. // Elasticsearch url (can be string if same url is used for all types).
  2.        $HISTORY['url']   = [
  3.              'uint' => 'http://localhost:9200',
  4.              'text' => 'http://localhost:9200'
  5.        ];
  6.        // Value types stored in Elasticsearch.
  7.        $HISTORY['types'] = ['uint', 'text'];

Example parameter values to fill the Zabbix frontend configuration file with:

  1. $HISTORY['url']   = 'http://test.elasticsearch.lan:9200';
  2.        $HISTORY['types'] = ['str', 'text', 'log'];

This configuration forces to store Text, Character and Log history values in Elasticsearch.

It is also required to make $HISTORY global in conf/zabbix.conf.php to ensure everything is working properly (see conf/zabbix.conf.php.example for how to do it):

  1. // Zabbix GUI configuration file.
  2.        global $DB, $HISTORY;
Installing Elasticsearch and creating mapping

Final two steps of making things work are installing Elasticsearch itself and creating mapping process.

To install Elasticsearch please refer to Elasticsearch installation guide.

Mapping is a data structure in Elasticsearch (similar to a table in a database). Mapping for all history data types is available here: database/elasticsearch/elasticsearch.map.

Creating mapping is mandatory. Some functionality will be broken if mapping is not created according to the instruction.

To create mapping for text type send the following request to Elasticsearch:

  1. curl -X PUT \
  2.         http://your-elasticsearch.here:9200/text \
  3.         -H 'content-type:application/json' \
  4.         -d '{
  5.           "settings": {
  6.              "index": {
  7.                 "number_of_replicas": 1,
  8.                 "number_of_shards": 5
  9.              }
  10.           },
  11.           "mappings": {
  12.              "properties": {
  13.                 "itemid": {
  14.                    "type": "long"
  15.                 },
  16.                 "clock": {
  17.                    "format": "epoch_second",
  18.                    "type": "date"
  19.                 },
  20.                 "value": {
  21.                    "fields": {
  22.                       "analyzed": {
  23.                          "index": true,
  24.                          "type": "text",
  25.                          "analyzer": "standard"
  26.                       }
  27.                    },
  28.                    "index": false,
  29.                    "type": "text"
  30.                 }
  31.              }
  32.           }
  33.        }'

Similar request is required to be executed for Character and Log history values mapping creation with corresponding type correction.

To work with Elasticsearch please refer to Requirement page for additional information.

Housekeeper is not deleting any data from Elasticsearch.

Storing history data in multiple date-based indices

This section describes additional steps required to work with pipelines and ingest nodes.

To begin with, you must create templates for indices.

The following example shows a request for creating uint template:

  1. curl -X PUT \
  2.         http://your-elasticsearch.here:9200/_template/uint_template \
  3.         -H 'content-type:application/json' \
  4.         -d '{
  5.           "index_patterns": [
  6.              "uint*"
  7.           ],
  8.           "settings": {
  9.              "index": {
  10.                 "number_of_replicas": 1,
  11.                 "number_of_shards": 5
  12.              }
  13.           },
  14.           "mappings": {
  15.              "properties": {
  16.                 "itemid": {
  17.                    "type": "long"
  18.                 },
  19.                 "clock": {
  20.                    "format": "epoch_second",
  21.                    "type": "date"
  22.                 },
  23.                 "value": {
  24.                    "type": "long"
  25.                 }
  26.              }
  27.           }
  28.        }'

To create other templates, user should change the URL (last part is the name of template), change "index_patterns" field to match index name and to set valid mapping, which can be taken from database/elasticsearch/elasticsearch.map.

For example, the following command can be used to create a template for text index:

  1. curl -X PUT \
  2.         http://your-elasticsearch.here:9200/_template/text_template \
  3.         -H 'content-type:application/json' \
  4.         -d '{
  5.           "index_patterns": [
  6.              "text*"
  7.           ],
  8.           "settings": {
  9.              "index": {
  10.                 "number_of_replicas": 1,
  11.                 "number_of_shards": 5
  12.              }
  13.           },
  14.           "mappings": {
  15.              "properties": {
  16.                 "itemid": {
  17.                    "type": "long"
  18.                 },
  19.                 "clock": {
  20.                    "format": "epoch_second",
  21.                    "type": "date"
  22.                 },
  23.                 "value": {
  24.                    "fields": {
  25.                       "analyzed": {
  26.                          "index": true,
  27.                          "type": "text",
  28.                          "analyzer": "standard"
  29.                       }
  30.                    },
  31.                    "index": false,
  32.                    "type": "text"
  33.                 }
  34.              }
  35.           }
  36.        }'

This is required to allow Elasticsearch to set valid mapping for indices created automatically. Then it is required to create the pipeline definition. Pipeline is some sort of preprocessing of data before putting data in indices. The following command can be used to create pipeline for uint index:

  1. curl -X PUT \
  2.         http://your-elasticsearch.here:9200/_ingest/pipeline/uint-pipeline \
  3.         -H 'content-type:application/json' \
  4.         -d '{
  5.           "description": "daily uint index naming",
  6.           "processors": [
  7.              {
  8.                 "date_index_name": {
  9.                    "field": "clock",
  10.                    "date_formats": [
  11.                       "UNIX"
  12.                    ],
  13.                    "index_name_prefix": "uint-",
  14.                    "date_rounding": "d"
  15.                 }
  16.              }
  17.           ]
  18.        }'

User can change the rounding parameter (“date_rounding”) to set a specific index rotation period. To create other pipelines, user should change the URL (last part is the name of pipeline) and change “index_name_prefix” field to match index name.

See also Elasticsearch documentation.

Additionally, storing history data in multiple date-based indices should also be enabled in the new parameter in Zabbix server configuration:

  1. ### Option: HistoryStorageDateIndex
  2.        # Enable preprocessing of history values in history storage to store values in different indices based on date.
  3.        # 0 - disable
  4.        # 1 - enable
  5.        #
  6.        # Mandatory: no
  7.        # Default:
  8.        # HistoryStorageDateIndex=0

Troubleshooting

The following steps may help you troubleshoot problems with Elasticsearch setup:

  1. Check if the mapping is correct (GET request to required index URL like http://localhost:9200/uint).
  2. Check if shards are not in failed state (restart of Elasticsearch should help).
  3. Check the configuration of Elasticsearch. Configuration should allow access from the Zabbix frontend host and the Zabbix server host.
  4. Check Elasticsearch logs.

If you are still experiencing problems with your installation then please create a bug report with all the information from this list (mapping, error logs, configuration, version, etc.)