Wymagania

  1. Wymagana jest usługa Elasticsearch w wersji 7 lub wyższej  (uruchamiana w poniższej sekcji Konfiguracja i punkcie 3).

Konfiguracja

  1. Wymagana jest instalacja Dockera wraz z Docker Compose. 
  2. W repozytorium kodu (lub docker-compose.yml) plusworkflow/plusworkflow-core znajduje się docker-compose.yml do uruchomienia elastica i Kibany lokalnie.
  3. W celu zmiany nazwy użytkownika i hasła do usługi należy zmodyfikować parametry ELASTIC_USERNAME i ELASTIC_PASSWORD w sekcji elasticsearch w pliku docker-compose.yml. 
    Należy też zmienić parametry ELASTICSEARCH_USERNAME i ELASTICSEARCH_PASSWORD sekcji kibana powyższego pliku (połączenie Kibany z usługą Elastica).

  4. Będąc w lokalizacji powyższego pliku docker-compose.yml należy wywołać:

    docker compose up

  5. Trzeba ustawić flagę w experimental.properties:

    elasticProcessSearch=true

  6. Dodać plik w katalogu domowym w configu: elastic.properties o zawartości:

    elastic.hostname=localhost
elastic.port=9200
elastic.username=elastic
elastic.password=elastic
#Opcjonalne
elastic.environment=
elastic.protocol=
  7. Opcjonalnie można podać parametr elastic.environment, który jest przydatny w przypadku jednej usługi Elasticsearch dla kilku instancji systemu. Podajemy w nim unikalną nazwę dla każdej z tych instancji. 
    Nazwa nie może zawierać następujących znaków: spacja, ", *, \, <, |, ,, >, /, ?

  8. Opcjonalnie można podać parametr elastic.protocol, który określa, czy komunikacja z usługą Elasticsearch powinna odbywać się po HTTPS, czy HTTP (W zależności od ustawień serwera). Podajemy w nim wartość https lub http. W przypadku braku parametru, komunikacja odbywa się domyślnie po HTTP.

    Jeżeli komunikacja z Elasticsearch odbywa się po HTTPS, to należy uzupełnić parametr elastic.protocol wartością https.
    Aby komunikacja z usługą działała poprawnie, należy wgrać ważny certyfikat do systemu. Można skorzystać z systemowej zakładki Certyfikaty.

  9. Włączyć parametr systemowy ElasticEnabled (jeśli istnieje)
  10. Dodać zadanie zaplanowane o nazwie: Indeksowanie procesów zadań. Po jego uruchomieniu zastaną zaindeksowane wszystkie procesy i zadania.
    Zadanie posiada parametr "Rozmiar części", który odpowiada za dzielenie indeksowanych danych. Manipulując nim można mieć wpływ na szybkość wykonywania zadania.
    Zadnie po przetworzeniu każdej z części zapisuje w parametrze systemowym ElasticLastIndexedProcessObjectId ID ostatniego zaindeksowanego procesu z paczki. W przypadku wystąpienia błędu podczas wykonywania zadania i po jego ponownym uruchomieniu zadanie wznowi indeksowanie od ID procesu zapisanego w parametrze. W celu zresetowania zadania, należy jako wartość parametru podać 0.

Problemy z wydajnością indeksowania

  1. Zmienić wartość -Xmx parametru ES_JAVA_OPTS sekcji elasticsearch w pliku docker-compose.yml na odpowiednio wyższą wartość. 

    Kontener elastica należy zaktualizować przy użyciu polecenia:

    docker compose up
  2. Zalecane jest stosowanie dysków SSD na maszynie, gdzie znajduje się usługa Elastic.
  3. W przypadku, gdy usługa Elastica znajduje się na serwerze w innej lokalizacji można zmniejszać wartość parametru "Rozmiar części" zadania zaplanowanego do indeksowania. Spowoduje to zmniejszenie requesta przesyłanego do Elastica.

  4. Spróbować zwiększyć limit przepustowości w Kibanie z poziomu zakładki Management -> Dev Tools wywołując (domyślnie jest to 20mb):

    PUT /_cluster/settings
{
  "persistent" : {
        "indices.store.throttle.max_bytes_per_sec" : "100mb"
   }
}

    Na czas indeksowania można też dokonać następującej zmiany:

    PUT /_cluster/settings
{
  "transient" : {
        "indices.store.throttle.type" : "none" 
   }
}

    Po skończonym indeksowaniu należy ustawić wartość "merge" tym samym poleceniem.

Obsługa Kibany

  1. Kibana uruchomiona z powyższej konfiguracji dostępna jest pod adresem: http://localhost:5601/ Dane dostępowe takie jak w elastic.properties powyżej.

  2. Przy pierwszym uruchomieniu Kibany trzeba ustawić patterny dla indeksów (process* dla procesów i activity* dla zadań).

  3. Zaindeksowane dokumenty przeglądamy w zakładce Discovery.
  4. W przypadku problemów ze zgodnością danych w elasticu (np. po zmianie typu jakiegoś indeksowanego pola) należy przejść do:

    Management -> Stack Management -> IndexManagement

    zaznaczyć wszystko (Include rollup indices i Include hidden indices muszą być odznaczone) i wybrać delete indices. Następnie trzeba przeindeksować wszystkie dokumenty zadaniem zaplanowanym.

  5. W przypadku wystąpienia błędu:

    Validation Failed: 1: this action would add [2] shards, but this cluster currently has [1000]/[1000] maximum normal shards open;

    Należy zwiększyć maksymalny limit aktywnych shard'ów z poziomu zakładki Management -> Dev Tools wywołując:

    PUT /_cluster/settings
{
  "persistent" : {
      "cluster.max_shards_per_node": "2000"
  }
}

  6. Usuwanie wiele indeksów na raz

    UWAGA. Usuwanie wielu indeksów bez znajomości składni może skutkować usunięciem nadmiarowej ilości danych.

    Domyślnie opcja usuwania wielu niejednoznacznych indeksów jest wyłączona.

    Aby móc korzystać z takiej opcji należy wywołać:

    PUT /_cluster/settings
{
  "transient": {
      "action.destructive_requires_name":false
  }
}

    Przykłady:

    1. Usuwanie indeksów z prefixem activity:

      DELETE /activity*


    2. Usuwanie wszystkich indeksów (ukryte indeksy nie zostaną usunięte):

      DELETE _all



Obsługa Dockera

  1. Usuwanie kontenerów - Będąc w lokalizacji pliku docker-compose.yml należy wywołać:

    docker compose down

    Jeżeli chcemy również usunąć wolumen ze wszystkimi danymi wywołujemy z opcją -v

    docker compose down -v

  2. Jeżeli chcemy utworzyć kontenery bez wyświetlania logów, dodajemy komendę -d

    docker compose up -d

  3. Aby wyświetlić status kontenerów należy wykonać:

    docker stats

Uwagi

  1. Po usunięciu/anulowaniu procesu lub zawieszeniu/anulowaniu/przywróceniu zadania z poziomu widoku wyników wyszukiwania daną mogą nie być spójne, należy ponowne wyszukać.
  2. Wyszukiwanie zadań z użyciem pól związanych z terminami ostatecznymi nie wyszukuje tylko zadań z terminami ostatecznymi.
  3. Zmienne tabelaryczne są wyświetlane wyłącznie w ramach jednego wiersza.

  4. Jeśli wystąpi poniższy błąd podczas eksportu wyników wyszukiwania do pliku:

    java.io.IOException: entity content is too long [356732089] for the configured buffer limit [104857600]

    to należy zmniejszyć wartość parametru systemowego PackSizeInAdvanceSearchExport. 

    Błąd ten oznacza, że request przesyłany do Elastica jest za duży (domyślnie jest to 100 MB). Istnieje możliwość zwiększenia tego limitu po stronie Elastica (bez zmniejszania parametru systemowego), jednak jest to niezalecane. 

    Limit można zwiększyć w pliku docker-compose.yml w sekcji elasticsearch -> environment, dodając linijkę:

    "http.max_content_length": "200mb"

    z odpowiednią wartością rozmiaru request'a. Kontener elastica należy zaktualizować przy użyciu polecenia:

    docker compose up

Przydatne linki:

  1. Jak działa elastic - https://www.elastic.co/blog/found-elasticsearch-top-down
  2. Multi-nodes docker - https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#docker-cli-run-dev-mode
  3. Wydajność - https://www.elastic.co/guide/en/elasticsearch/reference/8.6/tune-for-indexing-speed.html
    https://www.elastic.co/guide/en/elasticsearch/guide/master/indexing-performance.html
  4. Optymalizacja wyszukiwania - https://www.elastic.co/blog/found-optimizing-elasticsearch-searches/
  5. Wymagania sprzętowe - https://www.elastic.co/guide/en/elasticsearch/guide/master/hardware.html