Elasticsearch

Instalando o Elasticsearch

O Elasticsearch está disponivel para download no site https://www.elastic.co/downloads/elasticsearch. Deve ser utilizada a versão de Elasticsearch suportada pelo LumisXP de acordo com os requisitos de sistema. Para informações sobre instalação e configuração, veja o manual do Elasticsearch.

É importante observar que o Elasticsearch cria um cluster com outras instâncias que tenham o mesmo valor na configuração clusterName. É recomendado sempre alterar o valor do clusterName ao invés de deixar o valor padrão para evitar que outro Elasticsearch executado na mesma rede possa formar um cluster indesejado.

O Elasticsearch por padrão disponibiliza acesso pelas portas 9200 e 9300 e não há controle de acesso. Recomenda-se permitir os acessos às portas expostas pelo Elasticsearch apenas ao LumisXP.

O JVM utilizado para executar o Elasticsearch deve ser exatamente a mesma versão (incluindo número de update) da que está sendo utilizada para executar o LumisXP.

O Elasticsearch deve ser configurado para não criar os índices manipulados pelo portal automaticamente. Para isto, pode por exemplo, incluir no arquivo de configuração elasticsearch.yml a configuração action.auto_create_index: "-lumisportal-*,+*", se estiver usando no LumisXP a configuração de prefixo de índices "lumisportal", que é o padrão.

Por padrão, o Elasticsearch só permite 500 contextos de scroll simultâneos. Esse número é muito fácil de ser atingido. Quando esse limite é ultrapassado, o Elasticsearch gera em seu log uma mensagem como o exemplo abaixo:
Trying to create too many scroll contexts. Must be less than or equal to: [500]. This limit can be set by changing the [search.max_open_scroll_context] setting.
Quando esse erro acontece, erros na API de BigData podem acontecer. Por isso, sugerimos aumentá-lo para 100.000. Essa configuração deve, porém, ser adequada às demandas da solução. Para fazer essa configuração, basta incluir no arquivo de configuração elasticsearch.yml a configuração search.max_open_scroll_context: 100000.

O LumisXP, em algumas operações, limita a operação a determinados índices do Elasticsearch. Isso pode fazer com que uma linha de requisição grande seja gerada.
O Elasticsearch, por padrão, limita essa linha a 4kb. Para o correto funcionamento do LumisXP, é necessário aumentar essa configuração para 10mb (podendo precisar aumentar mais dependendo da solução adotada).
Para isso, basta incluir no arquivo de configuração elasticsearch.yml a configuração http.max_initial_line_length: 10MB.

Instalando o ICU Analysis Plugin

O LumisXP requer que o Elasticsearch tenha o plugin ICU Analysis instalado em todos os nós de Elasticsearch que serão utilizados.

Para instalar este plugin, em cada nó do Elasticsearch, execute o comando elasticsearch-plugin install analysis-icu na pasta bin da instalação do Elasticsearch. Instruções mais detalhadas sobre a instalação deste plugin estão disponíveis no manual do mesmo.

Configurações

Para configurar qual repositório de Big Data o LumisXP utiliza, acesse Configurações > Configurações do Portal > Configurações do Ambiente.

Mapeamento da pasta de análise

A pasta <lumisdata>/shared/data/elasticsearch/lumis-analysis deve ser mapeada para <config>/lumis-analysis em cada servidor do Elasticsearch utilizado pelo portal (por exemplo, através de mount point ou link simbólico).

Por exemplo, supondo que o LumisXP esteja sendo usado no Windows e sua instalação esteja em C:\lumis\lumisportal e que esteja sendo utilizado um Elasticsearch local, que está em C:\lumis\elasticsearch, o mapeamento poderia ser feito utilizando um junction point da seguinte forma: mklink /J "C:\lumis\elasticsearch\config\lumis-analysis" "C:\lumis\lumisportal\lumisdata\shared\data\elasticsearch\lumis-analysis".

Agora, supondo que o LumisXP esteja sendo usado no Linux e sua instalação esteja em /lumis/lumisportal e que esteja sendo utilizado um Elasticsearch local, com sua configuração em /etc/elasticsearch, o mapeamento poderia ser feito através de bind mounts da seguinte forma:
mkdir /etc/elasticsearch/lumis-analysis mount --bind /lumis/lumisportal/lumisdata/shared/data/elasticsearch/lumis-analysis /etc/elasticsearch/lumis-analysis

Criação de templates de índices para o uso com sinônimos

Caso a solução vá utilizar a funcionalidade de sinônimos e vá utilizar uma língua que não seja Português (código pt_BR), Inglês (código en_US) ou Espanhol (código es_ES), deverá ser criado um template de índice para a língua utilizada para criar os analisadores necessários para que os sinônimos sejam corretamente aplicados. Para maiores informações, veja a documentação técnica.

Problemas conhecidos

Em determinadas situações, o Elasticsearch pode gerar um erro caso uma busca gere muitos buckets de agregação.
Em especial, isso pode ocorrer caso seja feita uma segmentação de usuários utilizando uma das opções Fez a ação ou Não fez a ação.
Nesse caso, é possível que nos logs apareça uma mensagem como: TooManyBucketsException[Trying to create too many buckets. Must be less than or equal to: [10000] but was [10001]. This limit can be set by changing the [search.max_buckets] cluster level setting.]. A ação a ser tomada deve ser avaliada de caso a caso, mas recomendamos, no caso do problema se manifestar na segmentação de usuários, aumentar essa configuração (search.max_buckets) para 30.000, preferencialmente, de forma persistente. Para fazer essa configuração, basta incluir no arquivo de configuração elasticsearch.yml a configuração search.max_buckets: 30000.
Esse valor de 30.000 pode, no entanto, não ser o suficiente, caso a property bag lumis.service.analytics.usersegmentation.control.UserSegmentationData.subQueriesResultLimit tenha sido definida com um valor maior que esse.