Esta guía cubre la configuración de las versiones compatibles de Elasticsearch. Si usa una versión diferente, es posible que algunas funciones no trabajen como se espera.

Elasticsearch puede almacenar los siguientes tipos de valores:

Item value type	Database table	Elasticsearch type
Numeric (unsigned)	history_uint	uint
Numeric (float)	history	dbl
Character	history_str	str
Log	history_log	log
Text	history_text	text
Binary	history_bin	not supported by Zabbix
JSON	history_json	json

Elasticsearch no acepta matrices JSON. Un valor JSON debe ser un único objeto o un conjunto de objetos.

Notas importantes

Elasticsearch requiere libcurl. Consulte requirements para obtener más detalles.
El housekeeper no elimina datos de Elasticsearch. Para controlar durante cuánto tiempo se conservan los datos, consulte Index Lifecycle Management.
Zabbix no calcula ni almacena tendencias en Elasticsearch. Considere ampliar el periodo de almacenamiento del historial para conservar datos más antiguos.
Cuando se usa Elasticsearch, las consultas de rango que recuperan valores de la base de datos están limitadas por la marca de tiempo del periodo de almacenamiento de datos.
Elasticsearch no es compatible con los proxies de Zabbix.

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 fecha

En lugar de escribir todos los datos del historial en un único índice (por ejemplo, uint), Elasticsearch puede distribuir estos datos entre varios índices basados en fecha (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 index template para cada tipo de valor que desee almacenar; esto indica a Elasticsearch qué mapping aplicar cuando crea automáticamente un nuevo índice basado en fecha.
Crear un ingest pipeline para cada tipo de valor; este procesa cada valor entrante y lo dirige al índice correcto basado en fecha.

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 de Zabbix server

En el archivo de configuración de Zabbix server (zabbix_server.conf), establezca el parámetro HistoryProvider.

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

HistoryProvider=elasticsearch;value_types="str,log,text,json",url=http://localhost:9200

Si utiliza índices basados en fecha, añada date_index=1 al parámetro:

HistoryProvider=elasticsearch;value_types="str,log,text,json",url=http://localhost:9200,date_index=1

Después de realizar los cambios, reinicie Zabbix server:

systemctl restart zabbix-server

Configuración del frontend de Zabbix

En el archivo de configuración de tu frontend de Zabbix (zabbix.conf.php), establece la variable $HISTORY_PROVIDERS para que coincida con la configuración del server:

$HISTORY_PROVIDERS[] = [
  'types' => ['str','log','text','json'],
  'provider' => 'elasticsearch',
  'url' => 'http://localhost:9200'
];

Solución de problemas

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

Revise los registros de Elasticsearch o del server de Zabbix para detectar errores.
Para identificar consultas lentas, use la opción log_slow_queries en el parámetro de configuración del server de Zabbix HistoryProvider.
Verifique que Elasticsearch permita el acceso desde el server de Zabbix y el frontend de Zabbix.
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 mappings, templates y ingest pipelines 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 resolverlo.
Consulte Elasticsearch para ver si los datos recopilados por Zabbix están almacenados, por ejemplo:

curl 'http://localhost:9200/json/_search' \
 -H 'Content-Type: application/json' \
 -d '{
   "query": {
     "term": {
       "itemid": 42269
     }
   }
 }'

Si necesita restablecer su configuración de Elasticsearch y empezar de nuevo, puede eliminar todos los índices, templates e ingest pipelines:

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

What’s next?

Configuración de ClickHouse

Docs

Configuración de Elasticsearch

Notas importantes

Configuración de Elasticsearch

Almacenamiento del historial en un único índice

Tipo de valor JSON

Almacenamiento del historial en índices basados en fecha

Plantillas de índice

Canalizaciones de ingesta

Configuración de Zabbix server

Configuración del frontend de Zabbix

Solución de problemas

What’s next?

Suggest edit

Suggest an example

Thank you!