Table of Contents

8 Configuración de Elasticsearch

8 Configuración de Elasticsearch

Zabbix puede almacenar datos históricos en Elasticsearch como alternativa a una base de datos relacional.

El soporte de Elasticsearch es actualmente experimental.

Esta guía cubre la configuración para Elasticsearch 7.X. Si está utilizando una versión diferente, es posible que alguna funcionalidad no funcione como se espera.

La configuración implica crear una ubicación de almacenamiento de Elasticsearch para cada tipo de valor, configurar el preprocesamiento (si es necesario) y conectar Zabbix a su instancia de Elasticsearch.

Elasticsearch puede almacenar los siguientes tipos de valores:

Tipo de valor del item	Tabla de la base de datos	Tipo de Elasticsearch
Numérico (sin signo)	history_uint	uint
Numérico (coma flotante)	history	dbl
Carácter	history_str	str
Log	history_log	log
Texto	history_text	text
Binario	history_bin	no soportado por Zabbix
JSON	history_json	json

Notas importantes

Elasticsearch requiere libcurl. Consulte los requisitos para más detalles.
El housekeeper no elimina datos de Elasticsearch.
Si todos los datos históricos se almacenan en Elasticsearch, las tendencias no se calculan ni se almacenan en la base de datos. Considere ampliar el período de almacenamiento del historial.
Cuando se utiliza Elasticsearch, las consultas de rango que recuperan valores de la base de datos están limitadas por la marca de tiempo del período de almacenamiento de datos.
Elasticsearch no es compatible con Zabbix proxy; utilice SQLite en su lugar.

Si Elasticsearch aún no está instalado, consulte la guía oficial de instalación antes de continuar.

Configuración de Elasticsearch

Para almacenar datos históricos en Elasticsearch, debe:

Crear un índice para cada tipo de valor que desee almacenar; aquí es donde Elasticsearch almacena los datos, similar a una tabla en una base de datos relacional.
Definir un mapeo para cada índice; esto define la estructura de los datos, similar al esquema de una tabla.
Configurar una ingest pipeline para procesar los valores antes del almacenamiento (requerido para valores JSON e índices basados en fechas).

Elasticsearch puede almacenar datos en un único índice por tipo de valor o en varios índices basados en fechas. Ambos enfoques se describen a continuación.

Almacenamiento del historial en un único índice

En este enfoque, todos los datos históricos de un tipo de valor determinado se escriben en un único índice (por ejemplo, uint o text).

Para crear un índice para el tipo de valor Numérico (sin signo), envíe la siguiente solicitud (con /uint en la URL) a su instancia de Elasticsearch:

curl -X PUT \
        http://localhost:9200/uint \
        -H 'content-type:application/json' \
        -d '{
            "settings": {
             "index": {
                "number_of_replicas": 1,
                "number_of_shards": 5
             }
          },
          "mappings": {
             "properties": {
                "itemid": { "type": "long" },
                "clock": { "format": "epoch_second", "type": "date" },
                "value": { "type": "long" }
             }
          }
       }'

Elasticsearch responderá con una confirmación de que el índice fue creado:

{"acknowledged": true, "shards_acknowledged": true, "index": "uint"}

Se deben enviar solicitudes similares para cada tipo de valor adicional que desee almacenar en Elasticsearch.

Las asignaciones para todos los tipos de valor están disponibles en el repositorio fuente de Zabbix.

Por ejemplo, para crear un índice para el tipo de valor Texto:

curl -X PUT \
        http://localhost:9200/text \
        -H 'content-type:application/json' \
        -d '{
          "settings": {
             "index": {
                "number_of_replicas": 1,
                "number_of_shards": 5
             }
          },
          "mappings": {
             "properties": {
                "itemid": { "type": "long" },
                "clock": { "format": "epoch_second", "type": "date" },
                "value": {
                   "fields": {
                      "analyzed": { "index": true, "type": "text", "analyzer": "standard" }
                   },
                   "index": false,
                   "type": "text"
                }
             }
          }
       }'

Tipo de valor JSON

A diferencia de otros tipos de valores, los valores JSON requieren un procesamiento adicional antes de su almacenamiento.

El índice a continuación utiliza campos separados para los valores analizados y sin procesar, por lo que se necesita un ingest pipeline para analizar cada valor como JSON y almacenarlo en el campo correcto.

Para crear un índice para el tipo de valor JSON, envíe la siguiente solicitud (con /json en la URL) a su instancia de Elasticsearch.

curl -X PUT \
        http://localhost:9200/json \
        -H 'content-type:application/json' \
        -d '{
          "settings": {
             "number_of_shards": 5,
             "number_of_replicas": 1
          },
          "mappings": {
             "dynamic": false,
             "properties": {
                "itemid": { "type": "long" },
                "clock": { "type": "date", "format": "epoch_second" },
                "ns": { "type": "long" },
                "value_parsed": { "type": "flattened" },
                "value_raw": { "type": "keyword", "ignore_above": 1000000 }
           }
         }
       }'

Luego, cree el ingest pipeline:

curl -X PUT \
        http://localhost:9200/_ingest/pipeline/json \
        -H 'content-type:application/json' \
        -d '{
          "processors": [
             {
                "json": {
                   "field": "value",
                   "target_field": "value_parsed",
                   "ignore_failure": true
                }
             },
             {
                "set": {
                   "if": "ctx.value_parsed == null",
                   "field": "value_raw",
                   "value": "{{{ value }}}"
                }
             }
          ],
          "on_failure": [
             {
                "set": {
                   "field": "value_raw",
                   "value": "{{{ value }}}"
                }
             }
          ]
       }'

Elasticsearch responderá con una confirmación de que el ingest pipeline fue creado:

{"acknowledged": true}

Almacenamiento del historial en índices basados en fechas

En lugar de escribir todos los datos históricos en un único índice (por ejemplo, uint), Elasticsearch puede distribuir estos datos en varios índices basados en fechas (por ejemplo, uint-2026-01-01, uint-2026-01-02). Esto facilita la gestión del volumen de datos y la retención a lo largo del tiempo.

Para habilitar esto, debe:

Crear una plantilla de índice para cada tipo de valor que desee almacenar; esto le indica a Elasticsearch qué mapeo aplicar cuando crea automáticamente un nuevo índice basado en fechas.
Crear una ingest pipeline para cada tipo de valor; procesa cada valor entrante y lo enruta al índice basado en fechas correcto.
Configurar el parámetro HistoryStorageDateIndex en el archivo de configuración del server de Zabbix; esto permite almacenar valores en varios índices basados en fechas.

Plantillas de índice

Para crear una plantilla para el índice text, envíe una solicitud con los siguientes detalles:

Utilice _template/text_template en la URL de su instancia de Elasticsearch.
Utilice "text*" en el campo "index_patterns" para que coincida con el nombre del índice.
Utilice un mapeo para el tipo de valor text (consulte los mapeos en el repositorio fuente de Zabbix).

curl -X PUT \
        http://localhost:9200/_template/text_template \
        -H 'content-type:application/json' \
        -d '{
          "index_patterns": [ "text*" ],
          "settings": {
             "index": {
                "number_of_replicas": 1,
                "number_of_shards": 5
             }
          },
          "mappings": {
             "properties": {
                "itemid": { "type": "long" },
                "clock": { "format": "epoch_second", "type": "date" },
                "value": {
                   "fields": {
                      "analyzed": { "index": true, "type": "text", "analyzer": "standard" }
                   },
                   "index": false,
                   "type": "text"
                }
             }
          }
       }'

Plantilla para el índice json:

curl -X PUT \
        http://localhost:9200/_template/json_template \
        -H 'content-type:application/json' \
        -d '{
          "index_patterns": [ "json*" ],
          "settings": {
             "number_of_shards": 5,
             "number_of_replicas": 1
          },
          "mappings": {
             "dynamic": false,
             "properties": {
                "itemid": { "type": "long" },
                "clock": { "type": "date", "format": "epoch_second" },
                "ns": { "type": "long" },
                "value_parsed": { "type": "flattened" },
                "value_raw": { "type": "keyword", "ignore_above": 1000000 }
             }
          }
       }'

Canalizaciones de ingesta

Para crear una canalización de ingesta para el índice text:

Utilice _ingest/pipeline/text-pipeline en la URL de su instancia de Elasticsearch.
Incluya un procesador date_index_name para enrutar cada valor al índice basado en fecha correcto según su marca de tiempo.

curl -X PUT \
        http://localhost:9200/_ingest/pipeline/text-pipeline \
        -H 'content-type:application/json' \
        -d '{
          "description": "daily text index naming",
          "processors": [
             {
                "date_index_name": {
                   "field": "clock",
                   "date_formats": ["UNIX"],
                   "index_name_prefix": "text-",
                   "date_rounding": "d"
                }
             }
          ]
       }'

Para el índice json, la canalización también necesita analizar el valor JSON antes de enrutarlo al índice correcto:

curl -X PUT \
        http://localhost:9200/_ingest/pipeline/json-pipeline \
        -H 'content-type:application/json' \
        -d '{
          "description": "daily json index naming"
          "processors": [
             {
                "json": {
                   "field": "value",
                   "target_field": "value_parsed",
                   "ignore_failure": true
                }
             },
             {
                "script": {
                   "source": "if (ctx.value_parsed == null || !(ctx.value_parsed instanceof Map)) { ctx.value_raw = ctx.value; ctx.remove(\"value_parsed\"); }"
                }
             },
             {
                "date_index_name": {
                   "field": "clock",
                   "date_formats": [ "UNIX" ],
                   "index_name_prefix": "json-",
                   "date_rounding": "d"
                }
             }
          ]
       }'

Configuración del servidor Zabbix

En el archivo de configuración del servidor Zabbix (zabbix_server.conf), establezca los siguientes parámetros:

HistoryStorageURL: la URL de su instancia de Elasticsearch.
HistoryStorageTypes: lista separada por comas de los tipos de valores que se almacenarán en Elasticsearch.

Por ejemplo, para almacenar valores de tipo Character, Log, Text y JSON en Elasticsearch (mientras mantiene los valores Numeric en una base de datos):

HistoryStorageURL=http://localhost:9200
       HistoryStorageTypes=str,log,text,json

Si utiliza índices basados en fecha para todos los valores almacenados en Elasticsearch, también establezca el parámetro HistoryStorageDateIndex:

HistoryStorageDateIndex=1

Después de realizar los cambios, reinicie el servidor Zabbix:

systemctl restart zabbix-server

Configuración del frontend de Zabbix

En el archivo de configuración del frontend de Zabbix (zabbix.conf.php), declare $HISTORY como una variable global y establezca los valores de url y types para que coincidan con la configuración del server:

// Archivo de configuración de la GUI de Zabbix.
       global $DB, $HISTORY;
       
       $HISTORY['url']   = 'http://localhost:9200';
       $HISTORY['types'] = ['str', 'log', 'text', 'json'];

Solución de problemas

Los siguientes pasos pueden ayudarle a solucionar problemas con su configuración de Elasticsearch:

Verifique que auto_create_index esté habilitado:

curl -X GET \
        "http://localhost:9200/_cluster/settings?include_defaults=true&filter_path=**.auto_create_index"
       
       # {"defaults": {"action": {"auto_create_index": "false"} } }

Para habilitarlo, envíe la siguiente solicitud:

curl -X PUT \
        http://localhost:9200/_cluster/settings \
        -H 'content-type:application/json' \
        -d '{
          "persistent": {
             "action.auto_create_index": "true"
          }
       }'
       
       # {"acknowledged": true, "persistent": {"action": {"auto_create_index": "true"} }, "transient": {} }

Verifique que los mapeos, templates y pipelines de ingestión sean correctos enviando solicitudes GET a sus respectivas URLs:

curl -X GET http://localhost:9200/json
       curl -X GET http://localhost:9200/_template/json*
       curl -X GET http://localhost:9200/_ingest/pipeline/json*

Puede comparar las respuestas recibidas con las respuestas esperadas en la documentación de la API de Elasticsearch.

Compruebe si algún shard está en estado fallido; reiniciar Elasticsearch puede resolver esto.
Verifique que su configuración de Elasticsearch permita el acceso desde el Zabbix server y el Zabbix frontend.
Utilice el parámetro de configuración LogSlowQueries del Zabbix server para identificar consultas lentas.
Revise los registros de Elasticsearch en busca de errores.
Si necesita restablecer su configuración de Elasticsearch y comenzar de nuevo, puede eliminar todos los índices, templates y pipelines de ingestión:

curl -X DELETE "http://localhost:9200/_all"
       curl -X DELETE "http://localhost:9200/_template/*"
       curl -X DELETE "http://localhost:9200/_ingest/pipeline/*"

Documentation