Open the menu

    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 exceto se sua segurança for ativada. Se não for habilitar sua segurança, recomenda-se permitir os acessos às portas expostas pelo Elasticsearch apenas ao LumisXP. Sobre como habilitar sua segurança será detalhado mais abaixo em Configurações de Segurança.

    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.


    Configurações de Segurança

    A configuração de segurança no Elasticsearch é detalhado em seu manual. O LumisXP suporta autenticação usando API Key.

    Para habilitar a segurança em um Elasticsearch sendo usado pelo LumisXP, será necessário os passos abaixo. Observe que durante a execução destes passos o LumisXP não conseguirá acessar o Elasticsearch e gerará erros em seus logs por conta disso. Mas os erros devem parar de serem gerados no log uma vez que todos os passos forem completados com sucesso.

    1. Habilitar a configuração de segurança no Elasticsearch, incluindo habilitar API Key (xpack.security.authc.api_key.enabled: true), e reiniciá-lo.
    2. Gerar um API Key.
    3. No LumisXP, acessar Configurações > Configurações do Portal > Configurações do Ambiente e preencher os dados do API Key gerado, junto com as demais configurações de acesso ao Elasticsearch.

    No caso de uma instalação inicial do LumisXP, pode também seguir os passos acima. No caso de uma atualização de versão do LumisXP, é importante só alterar a configuração de segurança do Elastiscearch após o LumisXP entrar no ar, para que ele possa completar seu processo de atualização usando as configurações que ele já possuía antes de iniciar a atualização.


    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.