Šajā rokasgrāmatā aprakstīta atbalstīto versiju Elasticsearch iestatīšana. Zabbix serveris netiek palaists, ja jūsu Elasticsearch versija ir vecāka par minimālo atbalstīto versiju. Ja tā ir jaunāka par maksimālo atbalstīto versiju, Zabbix serveris tiek palaists tikai tad, ja AllowUnsupportedDBVersions parametra vērtība ir iestatīta uz 1.

Elasticsearch var glabāt šādus vērtību tipus:

Vienuma vērtības tips	Datubāzes tabula	Elasticsearch tips
Skaitlis (bez zīmes)	history_uint	uint
Skaitlis (peldošais komats)	history	dbl
Rakstzīme	history_str	str
Žurnāls	history_log	log
Teksts	history_text	text
Binārs	history_bin	Zabbix neatbalsta
JSON	history_json	json

Svarīgas piezīmes

Elasticsearch nepieciešama libcurl. Detalizētu informāciju skatiet sadaļā prasības.
Housekeeper nedzēš datus no Elasticsearch. Lai kontrolētu, cik ilgi dati tiek glabāti, skatiet Index Lifecycle Management.
Zabbix neaprēķina un nesaglabā tendenču datus Elasticsearch. Apsveriet iespēju pagarināt vēsturisko datu glabāšanas periodu, lai saglabātu vecākus datus.
Ja tiek izmantots Elasticsearch, diapazona vaicājumus, kas izgūst vērtības no datubāzes, ierobežo datu glabāšanas perioda laikspiedols.
Elasticsearch netiek atbalstīts Zabbix starpniekserveriem.
Sākot ar Elasticsearch 8.0, drošības līdzekļi pēc noklusējuma ir iespējoti: Elasticsearch pieprasa autentifikāciju un savā HTTP API izmanto HTTPS, sertifikātus parakstot ar automātiski ģenerētu CA. Šajā lapā sniegtajos piemēros tiek izmantots http://localhost:9200 bez autentifikācijas. Ja drošība ir iespējota, izmantojiet https:// URL un savos pieprasījumos norādiet CA sertifikātu un akreditācijas datus (piemēram, sudo curl --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic https://localhost:9200; CA sertifikāta failu var nolasīt tikai root lietotājs un elasticsearch grupa). Lai savienotu Zabbix serveri un Zabbix lietotāja saskarni ar šādu klasteri, skatiet sadaļu Savienojuma izveide ar aizsargātu klasteri.

Ja Elasticsearch vēl nav instalēts, pirms turpināšanas skatiet oficiālo instalēšanas rokasgrāmatu.

Elasticsearch konfigurēšana

Lai glabātu vēstures datus Elasticsearch, jums ir nepieciešams:

Izveidot indeksu katram vērtības tipam, ko vēlaties glabāt — šeit Elasticsearch glabā datus, līdzīgi kā tabulā relāciju datubāzē.
Definēt kartējumu katram indeksam — tas nosaka datu struktūru, līdzīgi kā tabulas shēma.
Iestatīt uzņemšanas konveijeru, lai apstrādātu vērtības pirms glabāšanas (nepieciešams JSON vērtībām un uz datumu balstītiem indeksiem).

Elasticsearch var glabāt datus vienā indeksā katram vērtības tipam vai vairākos uz datumu balstītos indeksos. Abas pieejas ir aprakstītas tālāk.

Vēstures datu glabāšana vienā indeksā

Izmantojot šo pieeju, visi vēstures dati konkrētam vērtības tipam tiek ierakstīti vienā indeksā (piemēram, uint vai text).

Lai izveidotu indeksu vērtības tipam Numeric (unsigned), nosūtiet tālāk norādīto pieprasījumu (ar /uint URL) savai Elasticsearch instancei:

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 atbildēs ar apstiprinājumu, ka indekss ir izveidots:

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

Līdzīgi pieprasījumi jānosūta par katru vērtības tipu, ko vēlaties glabāt Elasticsearch, tas ir, par katru tipu, kas norādīts Zabbix servera konfigurācijas opcijā value_types.

Kartējumi visiem vērtību tipiem ir pieejami Zabbix pirmkoda repozitorijā.

Piemēram, lai izveidotu indeksu vērtības tipam Text:

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"
         }
      }
   }
}'

JSON vērtības tips

Atšķirībā no citiem vērtību tipiem JSON vērtībām pirms saglabāšanas ir nepieciešama papildu apstrāde. JSON vērtības tipa indeksā katra vērtība tiek saglabāta vienā no diviem laukiem:

value_parsed — JSON objekti, kas tiek saglabāti kā flattened lauks, lai tos varētu meklēt pēc atslēgas un vērtības;
value_raw — visas pārējās JSON vērtības (masīvi, virknes, skaitļi, Būla vērtības un null), kas tiek saglabātas kā virkne.

Ingest pipeline parsē katru vērtību kā JSON un saglabā to pareizajā laukā. Vērtības, kas nav derīgs JSON, netiek nosūtītas uz Elasticsearch, jo vienumi, kas tās saņem, kļūst neatbalstīti.

Vispirms izveidojiet 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 atbildēs ar apstiprinājumu, ka ingest pipeline ir izveidots:

{"acknowledged": true}

Pēc tam izveidojiet indeksu JSON vērtības tipam, nosūtot tālāk norādīto pieprasījumu (ar /json URL) savai Elasticsearch instancei. Iestatījums default_pipeline liek Elasticsearch apstrādāt katru šajā indeksā ierakstīto vērtību, izmantojot json ingest pipeline. Šis iestatījums ir nepieciešams, jo Zabbix serveris, saglabājot vēsturi vienā indeksā, nenorāda ingest pipeline.

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 nevar indeksēt keyword un flattened vērtības, kas garākas par 32766 baitiem. Izmantojot "ignore_above": 8191, virknes, kas garākas par 8191 rakstzīmi, netiek indeksētas (un tās nevar meklēt), taču tās joprojām tiek saglabātas un pilnā apjomā atgrieztas Zabbix. Bez šī ierobežojuma Elasticsearch šādas vērtības noraida, un tās tiek zaudētas.

Vēstures glabāšana uz datumiem balstītos indeksos

Tā vietā, lai visus vēstures datus rakstītu vienā indeksā (piemēram, uint), Elasticsearch var sadalīt šos datus vairākos uz datumiem balstītos indeksos (piemēram, uint-2026-01-01, uint-2026-01-02). Tas atvieglo datu apjoma un glabāšanas termiņa pārvaldību laika gaitā.

Lai to iespējotu, jums ir jāveic šādas darbības:

Izveidojiet indeksa veidni katram vērtības tipam, ko vēlaties glabāt — tā nosaka Elasticsearch, kādu kartējumu piemērot, kad tas automātiski izveido jaunu uz datumu balstītu indeksu.
Izveidojiet ingest pipeline katram vērtības tipam — tas apstrādā katru ienākošo vērtību un novirza to uz pareizo uz datumu balstīto indeksu.

Indeksu veidnes

Lai izveidotu veidni text indeksam, nosūtiet pieprasījumu ar tālāk norādīto informāciju:

Izmantojiet _index_template/text_template sava Elasticsearch instances URL.
Laukā "index_patterns" izmantojiet "text-*", lai atbilstu uz datumu balstītu indeksu nosaukumiem.
Laukā "template" norādiet indeksa iestatījumus un kartējumu text vērtības tipam (skatiet kartējumus Zabbix avota repozitorijā).

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"
            }
         }
      }
   }
}'

Izveidojiet veidni katram vērtības tipam, ko vēlaties saglabāt, attiecīgi mainot veidnes nosaukumu, indeksa modeli un kartējumu.

Piemēram, veidne json indeksam (detalizētu informāciju par laukiem value_parsed un value_raw skatiet sadaļā JSON vērtības tips):

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 }
         }
      }
   }
}'

Izmantojiet kombinējamās indeksu veidnes (_index_template), kā parādīts iepriekš. Mantotās indeksu veidnes (_template) ir novecojušas, un Elasticsearch noraida mantotās veidnes, kuru indeksu modeļi pārklājas ar tā iebūvētajām veidnēm (piemēram, mantotu veidni ar modeli log* indeksam log).

Datu ievades konveijeri

Lai izveidotu datu ievades konveijeru text indeksam:

Izmantojiet _ingest/pipeline/text-pipeline sava Elasticsearch instances URL.
Iekļaujiet date_index_name procesoru, lai katru vērtību, pamatojoties uz tās laika zīmogu, novirzītu uz pareizo uz datumu balstīto indeksu.

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"
         }
      }
   ]
}'

Izveidojiet konveijeru katram glabājamās vērtības tipam, attiecīgi mainot konveijera nosaukumu, aprakstu un "index_name_prefix" vērtību. Konveijera nosaukumam jāsastāv no indeksa nosaukuma un sufiksa -pipeline (piemēram, uint-pipeline), jo Zabbix serveris izmanto šo nosaukumu, sūtot vērtības uz Elasticsearch.

Indeksam json konveijerim pirms vērtības novirzīšanas uz pareizo indeksu ir arī jāparsē JSON vērtība:

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"
         }
      }
   ]
}'

Zabbix servera konfigurēšana

Zabbix servera konfigurācijas failā (zabbix_server.conf) iestatiet parametru HistoryProvider.

Piemēram, lai Elasticsearch saglabātu Character, Log, Text un JSON tipa vērtības (saglabājot Numeric vērtības datubāzē):

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

Ja izmantojat uz datumu balstītus indeksus, pievienojiet parametram date_index=1:

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

Ja Elasticsearch drošības līdzekļi ir iespējoti, norādiet https:// URL ar akreditācijas datiem (skatiet Savienojuma izveide ar aizsargātu klasteri).

Pēc izmaiņu veikšanas restartējiet Zabbix serveri:

systemctl restart zabbix-server

Zabbix lietotāja saskarnes konfigurēšana

Zabbix lietotāja saskarnes konfigurācijas failā (zabbix.conf.php) iestatiet mainīgo $HISTORY_PROVIDERS, lai tas atbilstu servera konfigurācijai:

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

Ja Elasticsearch drošības līdzekļi ir iespējoti, norādiet to pašu https:// URL ar akreditācijas datiem, kas izmantoti servera konfigurācijā (skatiet Savienojuma izveide ar aizsargātu klasteri).

Savienojuma izveide ar aizsargātu klasteri

Ja Elasticsearch drošības līdzekļi ir iespējoti (pēc noklusējuma kopš Elasticsearch 8.0), Zabbix serverim un Zabbix lietotāja saskarnei ir jāuzticas Elasticsearch HTTP slāņa CA sertifikātam un jāautentificējas, izmantojot lietotājvārdu un paroli.

Izveidojiet lomu un lietotāju Zabbix vajadzībām. Tālāk norādītā loma ļauj Zabbix izgūt Elasticsearch versiju (klastera privilēģija monitor), izveidot indeksus, rakstīt un lasīt vēstures datus, kā arī dzēst vēstures datus, kad vienuma vēsture tiek notīrīta:

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" ]
}'

Pievienojiet Elasticsearch CA sertifikātu operētājsistēmas uzticamo sertifikātu sarakstam Zabbix servera un Zabbix lietotāja saskarnes hosts. Ja Zabbix darbojas citā hostā nekā Elasticsearch, vispirms nokopējiet CA sertifikātu (/etc/elasticsearch/certs/http_ca.crt) uz šo hostu. Piemēram, Debian/Ubuntu sistēmā:

sudo cp /etc/elasticsearch/certs/http_ca.crt /usr/local/share/ca-certificates/elasticsearch-http-ca.crt
sudo update-ca-certificates

Hosta nosaukumam URL ir jāatbilst Elasticsearch HTTP sertifikātam. Automātiski ģenerētais sertifikāts ir derīgs localhost, hosta nosaukumam un Elasticsearch hosta IP adresēm.

Norādiet akreditācijas datus URL gan Zabbix servera konfigurācijas failā, gan lietotāja saskarnes konfigurācijas failā. Ja parole satur speciālās rakstzīmes, kodējiet tās procentu formātā (piemēram, @ kā %40, : kā %3A un , kā %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'
];

Restartējiet Zabbix serveri un PHP-FPM (vai tīmekļa serveri, ja PHP darbojas kā tīmekļa servera modulis).

Problēmu novēršana

Tālāk norādītās darbības var palīdzēt novērst problēmas ar Elasticsearch iestatījumu:

Pārbaudiet Elasticsearch vai Zabbix servera žurnālus, vai tajos nav kļūdu. Piemēram, tālāk norādītie Zabbix servera žurnāla ziņojumi norāda uz problēmām, veidojot savienojumu ar aizsargātu klasteru (skatiet Savienojuma izveide ar aizsargātu klasteru):

cannot query Elasticsearch: SSL certificate problem: self-signed certificate in certificate chain—Elasticsearch CA sertifikāts nav uzticams;
cannot query Elasticsearch, HTTP error message: The requested URL returned error: 401—akreditācijas dati nav norādīti vai ir nepareizi;
cannot query Elasticsearch, HTTP error message: The requested URL returned error: 403—lietotājam nav nepieciešamo privilēģiju.

Zabbix lietotāja saskarne parāda līdzīgas kļūdas (piemēram, Elasticsearch error: missing authentication credentials for REST request).

Lai identificētu lēnus vaicājumus, iestatiet Zabbix servera konfigurācijas parametru LogSlowQueries. Ja vēstures nolasīšana no Elasticsearch aizņem ilgāku laiku par norādīto, Zabbix serveris žurnālā ieraksta slow query: <N> sec, "<query>". Gaidot Elasticsearch atbildi, Zabbix serveris arī ieraksta waiting for Elasticsearch response <N>sec ikreiz, kad paiet norādītais laiks, vai ik pēc 10 sekundēm, ja LogSlowQueries ir iestatīts uz 0.
Pārbaudiet, vai Elasticsearch atļauj piekļuvi no Zabbix servera un Zabbix lietotāja saskarnes.
Pārbaudiet, vai auto_create_index ir iespējots (pēc noklusējuma tas ir iespējots):

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

# {"persistent": {"action": {"auto_create_index": "false"} } }

Lai to iespējotu, nosūtiet šādu pieprasījumu:

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": {} }

Pārbaudiet, vai kartējumi, veidnes un datu ievades konveijeri ir pareizi, nosūtot GET pieprasījumus uz attiecīgajiem 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*"

Saņemtās atbildes varat salīdzināt ar paredzētajām atbildēm Elasticsearch API dokumentācijā.

Pārbaudiet, vai kāds no fragmentiem nav kļūmes stāvoklī; Elasticsearch restartēšana var novērst šo problēmu. Vienmezgla klasterī indeksiem ar replikām ("number_of_replicas": 1) ir dzeltens statuss, jo replikas nevar piešķirt tam pašam mezglam, kuram piešķirti primārie fragmenti; tas neietekmē Zabbix. Lai no tā izvairītos, iestatiet "number_of_replicas" uz 0.
Vaicājiet Elasticsearch, lai pārbaudītu, vai Zabbix apkopotie dati ir saglabāti, piemēram:

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

Ja nepieciešams atiestatīt Elasticsearch iestatījumu un sākt no jauna, dzēsiet Zabbix izveidotos indeksus, indeksu veidnes un datu ievades konveijerus (tādējādi tiek dzēsti visi Elasticsearch saglabātie vēstures dati). Pēc noklusējuma Elasticsearch neļauj dzēst indeksus, izmantojot aizstājējzīmju izteiksmes, tāpēc, lai dzēstu uz datumiem balstītus indeksus, īslaicīgi mainiet iestatījumu action.destructive_requires_name. Indeksu veidnes un datu ievades konveijeri jādzēš pa vienam; pieprasījumi veidnēm vai konveijeriem, kas nepastāv, atgriež kļūdu, kuru var ignorēt.

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"

Kas tālāk?

ClickHouse iestatīšana

Docs

Elasticsearch iestatīšana