Configuración de Elasticsearch

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

Esta guía abarca la configuración de las versiones compatibles de Elasticsearch. El server de Zabbix no se inicia si la versión de Elasticsearch es anterior a la versión mínima compatible. Si es posterior a la versión máxima compatible, el server de Zabbix se inicia únicamente si el parámetro AllowUnsupportedDBVersions está establecido en 1.

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 (flotante) history dbl
Carácter history_str str
Registro history_log log
Texto history_text text
Binario history_bin no compatible con Zabbix
JSON history_json json

Notas importantes

  • Elasticsearch requiere libcurl. Consulta requisitos para obtener más información.
  • El housekeeper no elimina datos de Elasticsearch. Para controlar durante cuánto tiempo se conservan los datos, consulta Index Lifecycle Management.
  • Zabbix no calcula ni almacena tendencias en Elasticsearch. Considera ampliar el periodo de almacenamiento del historial para conservar los datos antiguos.
  • 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 periodo de almacenamiento de datos.
  • Elasticsearch no es compatible con los proxy de Zabbix.
  • A partir de Elasticsearch 8.0, las funciones de seguridad están habilitadas de forma predeterminada: Elasticsearch requiere autenticación y utiliza HTTPS para su API HTTP, con certificados firmados por una CA generada automáticamente. Los ejemplos de esta página utilizan http://localhost:9200 sin autenticación. Si la seguridad está habilitada, utiliza una URL https:// y proporciona el certificado de la CA y las credenciales en tus solicitudes (por ejemplo, sudo curl --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic https://localhost:9200; el archivo del certificado de la CA solo puede ser leído por root y el grupo elasticsearch). Para conectar el server de Zabbix y el frontend de Zabbix a dicho clúster, consulta Conexión a un clúster protegido.

Si Elasticsearch aún no está instalado, consulta 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.

Almacenar el historial en un único índice

Con este enfoque, todos los datos del historial 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 se ha creado:

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

Deben enviarse solicitudes similares para cada tipo de valor que desee almacenar en Elasticsearch, es decir, para cada tipo incluido en la opción value_types de la configuración del server de Zabbix.

Las asignaciones para todos los tipos de valor están disponibles en el repositorio de código 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 valor, los valores JSON requieren un procesamiento adicional antes de almacenarse. El índice para el tipo de valor JSON almacena cada valor en uno de dos campos:

  • value_parsed: objetos JSON, almacenados como un campo flattened, para que se puedan buscar por clave y valor;
  • value_raw: todos los demás valores JSON (matrices, cadenas, números, valores booleanos y null), almacenados como una cadena.

Un ingest pipeline analiza cada valor como JSON y lo almacena en el campo correcto. Los valores que no son JSON válidos no se envían a Elasticsearch, porque los items que los reciben pasan a ser no compatibles.

Primero, 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
         }
      },
      {
         "script": {
            "source": "if (ctx.value_parsed == null || !(ctx.value_parsed instanceof Map)) { ctx.value_raw = ctx.value; ctx.remove(\"value_parsed\"); }"
         }
      }
   ]
}'

Elasticsearch responderá con una confirmación de que se creó el ingest pipeline:

{"acknowledged": true}

A continuación, cree un índice para el tipo de valor JSON enviando la siguiente solicitud (con /json en la URL) a su instancia de Elasticsearch. La configuración default_pipeline hace que Elasticsearch procese cada valor escrito en este índice con el ingest pipeline json. Esta configuración es necesaria porque Zabbix server no especifica un ingest pipeline al almacenar el historial en un único índice.

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

Elasticsearch no puede indexar valores keyword y flattened de más de 32766 bytes. Con "ignore_above": 8191, las cadenas de más de 8191 caracteres no se indexan (y no se pueden buscar), pero se siguen almacenando y devolviendo a Zabbix completas. Sin este límite, Elasticsearch rechaza dichos valores y se pierden.

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 índices

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

  • Use _index_template/text_template en la URL de su instancia de Elasticsearch.
  • Use "text-*" en el campo "index_patterns" para coincidir con los nombres de los índices basados en fechas.
  • En el campo "template", especifique la configuración del índice y una asignación para el tipo de valor text (consulte las asignaciones en el repositorio de código fuente de Zabbix).
curl -X PUT \
 http://localhost:9200/_index_template/text_template \
 -H 'content-type:application/json' \
 -d '{
   "index_patterns": [ "text-*" ],
   "template": {
      "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"
            }
         }
      }
   }
}'

Cree una plantilla para cada tipo de valor que desee almacenar, cambiando el nombre de la plantilla, el patrón del índice y la asignación según corresponda.

Por ejemplo, una plantilla para el índice json (para obtener información sobre los campos value_parsed y value_raw, consulte Tipo de valor JSON):

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

Use plantillas de índices componibles (_index_template), como se muestra arriba. Las plantillas de índices heredadas (_template) están obsoletas, y Elasticsearch rechaza las plantillas heredadas cuyos patrones de índice se superponen con sus plantillas integradas (por ejemplo, una plantilla heredada con el patrón log* para el índice log).

Pipelines de ingesta

Para crear un pipeline de ingesta para el índice text:

  • Use _ingest/pipeline/text-pipeline en la URL de su instancia de Elasticsearch.
  • Incluya un procesador date_index_name para dirigir cada valor al índice correcto basado en la fecha, 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"
         }
      }
   ]
}'

Cree un pipeline para cada tipo de valor que desee almacenar, cambiando el nombre del pipeline, la descripción y el valor de "index_name_prefix" según corresponda. El nombre del pipeline debe constar del nombre del índice y el sufijo -pipeline (por ejemplo, uint-pipeline), porque Zabbix server utiliza este nombre al enviar valores a Elasticsearch.

Para el índice json, el pipeline también debe analizar el valor JSON antes de dirigirlo 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 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 fechas, añada date_index=1 al parámetro:

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

Si las funciones de seguridad de Elasticsearch están habilitadas, especifique una URL https:// con credenciales (consulte Conexión a un clúster protegido).

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

systemctl restart zabbix-server

Configuración del frontend de Zabbix

En tu archivo de configuración del 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'
];

Si las funciones de seguridad de Elasticsearch están habilitadas, especifica la misma URL https:// con las credenciales que en la configuración del server (consulta Conexión a un clúster protegido).

Conexión a un clúster protegido

Si las funciones de seguridad de Elasticsearch están habilitadas (de forma predeterminada desde Elasticsearch 8.0), el server de Zabbix y el frontend de Zabbix deben confiar en el certificado de la CA de la capa HTTP de Elasticsearch y autenticarse con un nombre de usuario y una contraseña.

  1. Cree un rol y un usuario para Zabbix. El siguiente rol permite a Zabbix recuperar la versión de Elasticsearch (el privilegio de clúster monitor), crear índices, escribir y leer datos históricos, y eliminar datos históricos cuando se borra el historial de un item:
sudo curl -X PUT \
 --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic \
 https://localhost:9200/_security/role/zabbix_history \
 -H 'content-type:application/json' \
 -d '{
   "cluster": [ "monitor" ],
   "indices": [
      {
         "names": [ "uint", "uint-*", "dbl", "dbl-*", "str", "str-*", "log", "log-*", "text", "text-*", "json", "json-*" ],
         "privileges": [ "create_index", "index", "read", "delete" ]
      }
   ]
}'
sudo curl -X PUT \
 --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic \
 https://localhost:9200/_security/user/zabbix \
 -H 'content-type:application/json' \
 -d '{
   "password": "<password>",
   "roles": [ "zabbix_history" ]
}'
  1. Añada el certificado de la CA de Elasticsearch a los certificados de confianza del sistema operativo en los hosts del server de Zabbix y del frontend de Zabbix. Si Zabbix se ejecuta en un host diferente al de Elasticsearch, copie primero el certificado de la CA (/etc/elasticsearch/certs/http_ca.crt) a ese host. Por ejemplo, en Debian/Ubuntu:
sudo cp /etc/elasticsearch/certs/http_ca.crt /usr/local/share/ca-certificates/elasticsearch-http-ca.crt
sudo update-ca-certificates

El nombre del host en la URL debe coincidir con el certificado HTTP de Elasticsearch. El certificado generado automáticamente es válido para localhost, el nombre del host y las direcciones IP del host de Elasticsearch.

  1. Especifique las credenciales en la URL, tanto en el archivo de configuración del server de Zabbix como en el archivo de configuración del frontend. Si la contraseña contiene caracteres especiales, codifíquelos mediante porcentajes (por ejemplo, @ como %40, : como %3A y , como %2C).
HistoryProvider=elasticsearch;value_types="str,log,text,json",url=https://zabbix:<password>@localhost:9200
$HISTORY_PROVIDERS[] = [
  'types' => ['str','log','text','json'],
  'provider' => 'elasticsearch',
  'url' => 'https://zabbix:<password>@localhost:9200'
];
  1. Reinicie el server de Zabbix y PHP-FPM (o el web server, si PHP se ejecuta como un módulo del web server).

Solución de problemas

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

  1. Compruebe los registros de Elasticsearch o del server de Zabbix para detectar errores. Por ejemplo, los siguientes mensajes del registro del server de Zabbix indican problemas al conectarse a un clúster protegido (consulte Conexión a un clúster protegido):
  • cannot query Elasticsearch: SSL certificate problem: self-signed certificate in certificate chain: el certificado de la CA de Elasticsearch no es de confianza;
  • cannot query Elasticsearch, HTTP error message: The requested URL returned error: 401: faltan las credenciales o son incorrectas;
  • cannot query Elasticsearch, HTTP error message: The requested URL returned error: 403: el usuario no tiene los privilegios necesarios.

El frontend de Zabbix muestra errores similares (por ejemplo, Elasticsearch error: missing authentication credentials for REST request).

  1. Para identificar consultas lentas, establezca el parámetro de configuración del server de Zabbix LogSlowQueries. Si la lectura del historial desde Elasticsearch tarda más del tiempo especificado, el server de Zabbix registra slow query: <N> sec, "<query>". Mientras espera una respuesta de Elasticsearch, el server de Zabbix también registra waiting for Elasticsearch response <N>sec cada vez que transcurre el tiempo especificado, o cada 10 segundos si LogSlowQueries está establecido en 0.

  2. Verifique que Elasticsearch permita el acceso desde el server y el frontend de Zabbix.

  3. Verifique que auto_create_index esté habilitado (está habilitado de forma predeterminada):

curl -X GET \
 "http://localhost:9200/_cluster/settings?include_defaults=true&filter_path=**.auto_create_index"

# {"persistent": {"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": {} }
  1. Verifique que las asignaciones, los templates y las canalizaciones de ingesta sean correctos enviando solicitudes GET a sus respectivas URL:
curl -X GET "http://localhost:9200/json*"
curl -X GET "http://localhost:9200/_index_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.

  1. Compruebe si algún shard se encuentra en estado fallido; reiniciar Elasticsearch puede resolver el problema. En un clúster de un solo nodo, los índices con réplicas ("number_of_replicas": 1) tienen el estado amarillo, porque las réplicas no se pueden asignar al mismo nodo que los shards primarios; esto no afecta a Zabbix. Para evitarlo, establezca "number_of_replicas" en 0.

  2. Consulte Elasticsearch para comprobar 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
     }
   }
 }'
  1. Si necesita restablecer la configuración de Elasticsearch y comenzar de nuevo, elimine los índices, los templates de índices y las canalizaciones de ingesta creados para Zabbix (esto elimina todos los datos históricos almacenados en Elasticsearch). De forma predeterminada, Elasticsearch no permite eliminar índices mediante expresiones comodín, por lo que, para eliminar índices basados en fechas, cambie temporalmente la configuración action.destructive_requires_name. Los templates de índices y las canalizaciones de ingesta deben eliminarse uno por uno; las solicitudes para templates o canalizaciones que no existen devuelven un error, que se puede ignorar.
curl -X DELETE "http://localhost:9200/uint,dbl,str,log,text,json?ignore_unavailable=true"

curl -X PUT \
 http://localhost:9200/_cluster/settings \
 -H 'content-type:application/json' \
 -d '{"persistent": {"action.destructive_requires_name": false}}'
curl -X DELETE "http://localhost:9200/uint-*,dbl-*,str-*,log-*,text-*,json-*" 
curl -X PUT \
 http://localhost:9200/_cluster/settings \
 -H 'content-type:application/json' \
 -d '{"persistent": {"action.destructive_requires_name": null}}'

for type in uint dbl str log text json; do
  curl -X DELETE "http://localhost:9200/_index_template/${type}_template"
  curl -X DELETE "http://localhost:9200/_ingest/pipeline/${type}-pipeline"
done
curl -X DELETE "http://localhost:9200/_ingest/pipeline/json"