Problema

Os sistemas geram logs muito volumosos, de difícil análise e administração, tornando complexa a gestão por parte do cliente.

Para contornar limitações de espaço em disco, normalmente o cliente adota uma destas soluções:

  • configura os logs com nível mínimo de detalhes, para que os arquivos fiquem pequenos;
  • rotaciona e elimina os logs com alta frequência;

Estas soluções levam à perda de informações importantes no momento de análise de um problema.


Cenário comum:

  • o cliente abre chamado reportando um problema, porém não tem o log em nível detalhado, ou então possui log detalhado apenas das últimas horas e não do momento do erro;
  • com isso recebe orientação para aumentar o nível de log e provocar o problema novamente, e isso nem sempre é factível, especialmente em problemas mais graves, como queda de serviços;
  • muitas vezes não é possível reproduzir no ambiente de homologação o problema exato que ocorreu na produção;
  • como consequência, a atuação do suporte fica prejudicada, aumentando o tempo de atendimento, a quantidade de iterações e esforço de investigação, para todos os envolvidos.

Precisamos de uma forma mais robusta de armazenar e consultar logs recentes sem comprometer a operação e minimizando impactos ao usuário final.


Solução proposta

Definir uma configuração para possibilitar gerenciamento ativo dos logs gerados pelo sistema, que possa ser implantado pelo próprio cliente na sua estrutura e utilizado para agilizar análises, consultorias, atendimentos de suporte e situações relacionadas.


Escopo

Esta documentação cobre um método para gerenciamento dos logs do Progress 12 PASOE que já utilizamos internamente e recomendamos aos clientes.

A mesma tecnologia pode ser utilizada para qualquer outro tipo de log, como Progress Clientlog, Tomcat, Apache, etc.

Reforçamos que esta não é a única solução que existe, e nem a única forma de fazer. Aqui tivemos a intenção de definir uma solução simples e 100% utilizando software livre. O cliente pode ficar à vontade para experimentar outros tipos de ferramentas.

  • A TOTVS não se compromete com suporte a este serviço (bugs da ferramenta, atualização futura, etc).


O setup que propomos utiliza 3 ferramentas que fazem parte do Elastic Stack para coletar, armazenar e consultar os logs:

  • Filebeat - agente que monitora os logs do Datasul e envia continuamente para o banco de dados;
  • Elasticsearch - o banco de dados propriamente dito - coração de todo o stack;
  • Kibana - interface gráfica para aplicar queries sobre o banco e mostrar os resultados;

  • O Elastic Stack possui outras ferramentas, inclusive de Machine Learning, mas neste escopo estamos adotando apenas soluções mais simples e sem custo.


Impacto na estrutura

A única alteração prevista para as máquinas já existentes é garantir que o log do PASOE esteja sendo gerado com alto nível de detalhes, e rotacionado dentro de um tempo adequado para impedir risco de estouro de disco.

Já para o Elastic Stack, recomendamos a criação de uma nova Virtual Machine, para concentrar todas as configurações e isolar todos os processos, evitando qualquer risco de desestabilização dos sistemas já existentes.


Configurar nível de log do PASOE

Seguir as recomendações deste link: https://centraldeatendimento.totvs.com/hc/pt-br/articles/10403011775255-Framework-Linha-Datasul-TEC-Alterar-o-n%C3%ADvel-de-log-do-PASOE


Rotacionamento dos logs do PASOE

Na máquina onde o PASOE é executado, configure uma rotina (exemplos completos mais abaixo) para executar periodicamente o comando de rotacionamento do log. Mais detalhes neste link: https://centraldeatendimento.totvs.com/hc/pt-br/articles/18741602158999-Framework-Linha-Datasul-TEC-Como-rotacionar-logs-do-PASOE


Abaixo seguem exemplos dos scripts que utilizamos internamente na Totvs, que podem ser customizados conforme a sua necessidade. O que essa versão faz:

  • Rotaciona os logs PASOE quando excedem o tamanho de 20 MB
  • Eliminam o histórico de logs rotacionados quando atingem 60 minutos sem alteração


Linux

Opcionalmente, recomenda-se editar no arquivo <$DLC>/servers/pasoe/bin/tcmanager.sh a variável _subdir conforme abaixo, para criar as pastas de rotacionamento no formato AAAA-MM-DD_HH-MM-SS, tornando mais fácil a identificação:

Próximo a linha 2821, trocar:

        _subdir="`date +"%m-%d-%Y-%H%M%S"`"

por

        _subdir="`date +"%Y-%m-%d_%H-%M-%S"`"


Baixar e salvar o arquivo quebrar_log_pasoe_linux.sh na sua estrutura, por exemplo:

/opt/totvs/scripts/quebrar_log_pasoe_linux.sh


Configurar chamada periódica na cron do Linux (crontab -e) conforme sua necessidade. Exemplos:

  • 0 * * * * /opt/totvs/scripts/quebrar_log_pasoe_linux.sh # de hora em hora
  • * * * * * /opt/totvs/scripts/quebrar_log_pasoe_linux.sh # de minuto em minuto
  • 0,15,30,45 * * * * /opt/totvs/scripts/quebrar_log_pasoe_linux.sh # a cada 15 minutos



Windows

Primeiramente o arquivo <$DLC>\servers\pasoe\bin\tcmanager.ps1 precisa ser atualizado, para corrigir um bug reconhecido pela Progress. Detalhes neste link: https://centraldeatendimento.totvs.com/hc/pt-br/articles/18742185170839-Framework-Linha-Datasul-TEC-The-process-cannot-access-the-file-agent-log-filename-because-it-is-being-used-by-another-process


Baixar e descompactar o arquivo quebrar-log-pasoe-tcman-clean.zip na sua estrutura, por exemplo:

c:\totvs\scripts\quebrar-log-pasoe-tcman-clean.ps1


Configurar Chamada periódica no Windows Task Scheduler conforme sua necessidade (a cada minuto, de hora em hora, 15 em 15 minutos, etc), exemplo:




Requisitos de hardware para a nova VM do Elastic Stack

Descrevemos aqui a configuração que estamos utilizando internamente para os ambientes de desenvolvimento. Cenários de produção dos clientes podem demandar de configurações diferentes, especialmente no quesito Disco, dependendo do volume de logs e quantidade de tempo que desejar armazená-los.

Recomendamos criar uma nova Virtual Machine exclusiva para este setup, para isolar os processos e garantir que as demais máquinas utilizadas para o sistema não sejam afetadas.

  • Sistema Operacional: Oracle Linux 8 (pode ser outro. Utilizamos este por ser homologado para uso internamente na Totvs).
  • Disco: 500 GB (hoje estamos gerenciando logs de 10 ambientes e mantendo histórico por 7 dias. 500 GB está se mostrando suficiente).
  • Memória: 8 GB (dependendo da quantidade de logs a administrar e usuários que realizarão consultas, pode ser interessante mais memória, para otimizar a performance).
  • Processadores: 4 núcleos (dependendo da quantidade de logs a administrar e usuários que realizarão consultas, pode ser interessante mais núcleos, para otimizar a performance).


Passo a passo para a instalação

Elasticsearch

Instalação

Vamos começar pelo banco de dados, que é a parte mais importante de todo o stack. Inicialmente faremos a instalação padrão conforme a documentação da ferramenta (executar os comandos abaixo no prompt do Linux):


1. Garantir que os pacotes estejam atualizados no Sistema operacional:

sudo dnf update -y


2. Adicionar o repositório do Elasticsearch (chave GPG):

sudo rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch


3. Criar o arquivo do repositório:

echo "[elasticsearch-8.x]
name=Elasticsearch repository for 8.x packages
baseurl=https://artifacts.elastic.co/packages/8.x/yum
gpgcheck=1
gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
enabled=1
autorefresh=1
type=rpm-md" | sudo tee /etc/yum.repos.d/elasticsearch.repo


4. Instalar o Elasticsearch:

sudo dnf install -y elasticsearch


Configuração e utilização

Neste momento vamos configurar o Elasticsearch da forma mais simples, sem autenticação, apenas para permitir acesso via interface gráfica (Kibana), pois será mais simples fazer configurações avançadas por lá. Posteriormente voltaremos para configurar a segurança. Também não vamos usar autenticação https, apenas http, visto que todo o escopo fica concentrado na máquina dedicada. O cliente fica livre para configurar segurança mais avançada, que não será tratada neste documento.


1. Vamos editar as configurações no arquivo /etc/elasticsearch/elasticsearch.yml (tenha atenção redobrada com todos os arquivos *.yml, pois erros de identação causam falha de execução. Mesmo padrão do python):

Atenção especial para estes campos:

&&&&& revisar, talvez volte a tratar a segurança desde o início &&&&&

path.data: /var/lib/elasticsearch # é neste diretório que os dados serão armazenados, portanto aponte para uma pasta (ou volume) com ao menos 500 GB disponíveis.
path.logs: /var/log/elasticsearch # os logs do elasticsearch serão fundamentais para mitigar quaisquer problemas durante a configuração.
xpack.security.enabled: false # mais adiante voltaremos aqui para mudar para true
xpack.security.enrollment.enabled: false
xpack.security.http.ssl:
    enabled: false
xpack.security.transport.ssl:
    enabled: false

A porta default do Elasticsearch é 9200. Se necessário, altere diretamente no arquivo. Neste setup vamos manter o default.

Exemplo da identação correta no arquivo:


2. Habilitar e iniciar o serviço:

sudo systemctl enable --now elasticsearch


3. Já com o serviço no ar, vamos gerar a senha para o usuário padrão elastic. Esta senha precisará ser usada futuramente nas chamadas à API do Elasticsearch (a senha será solicitada no prompt):

sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic -i


4. O print abaixo mostra o comando para validar se o Elasticsearch está rodando corretamente e o resultado esperado (quando solicitado informe a mesma senha que você definiu acima):


5. Agora vamos criar o usuário kibana_system_user, que será utilizado para o serviço do Kibana comunicar via API com o Elasticsearch.

Execute o comando abaixo no prompt do Linux com curl, informando a senha desejada no lugar de <SENHA>:

-X POST -u elastic -H "Content-Type: application/json" "http://localhost:9200/_security/user/kibana_system_user" -d '{ "password" : "<SENHA>", "roles" : [ "kibana_system" ], "full_name" : "Kibana System User", "enabled": true}'

Exemplo:


6. Em seguida vamos criar o usuário kibana_admin, que será utilizado para fazermos login na interface gráfica do Kibana e realizarmos ações administrativas.

Execute com curl, informando a senha desejada no lugar de <SENHA>:

-X POST -u elastic -H "Content-Type: application/json" "http://localhost:9200/_security/user/kibana_admin" -d '{ "password" : "<SENHA>", "roles" : [ "superuser" ], "full_name" : "Kibana Admin", "enabled": true}'

Exemplo:



Kibana

Instalação

Agora que temos a configuração básica do Elasticsearch, vamos instalar a interface gráfica, pois através dela será mais simples realizar as demais configurações do Elasticsearch.

1. Instalação padrão do Kibana:

sudo dnf install -y kibana


Configuração e utilização

1. Após instalado, vamos editar as configurações no arquivo /etc/kibana/kibana.yml:

Atenção especial para estes campos:

  • server.port: 8080 # por default a porta do Kibana é 5601. Aqui internamente optamos por utilizar a 8080 por ser mais adequada ao nosso modelo de redes e segurança.
  • server.host: "0.0.0.0" # fizemos esta configuração para permitir acesso à interface gráfica à partir de qualquer ponto da rede. Restrinja de acordo com a sua necessidade. #
  • elasticsearch.username: "kibana_system_user" # usuário que foi criado na etapa anterior para permitir que o Kibana faça login no Elasticsearch para realizar queries e aplicar alterações de configurações.
  • elasticsearch.password: "<SENHA>" # senha que você definiu para o usuário kibana_system_user. Este setup permite que a senha fique legível no arquivo. Por ser algo controlado na rede interna, isso nos atende. Mas você pode optar por utilizar um formato mais robusto, seguindo a documentação oficial do Kibana, que não vamos tratar neste manual.

Exemplo (no cenário de teste a senha foi criada igual ao nome do usuário):


2. Habilitar e executar o serviço:

sudo systemctl enable --now kibana


3. No navegador, acesse http://<servidor|IP>:porta/. Exemplo:

http://10.171.42.84:8080/

Vamos fazer login com o usuário kibana_admin, que criamos logo acima:


4. A partir deste ponto vamos concentrar as ações na janela Dev Tools:


5. No Dev Tools, vamos criar a política de ILM. &&&&&




6. Vamos criar o Index Template pasoe-logs-template. Mais adiante ele será associado ao filebeat para garantir que os logs do PASOE sejam associados à política de ILM, além de tratar o campo especial keyword, para permitir consulta Case Sensitive nas mensagens.

Cole e execute o código abaixo no Dev Tools:

PUT _index_template/pasoe-logs-template
{
  "index_patterns": ["pasoe-logs-*"],
  "template": {
    "settings": {
      "index": {
        "lifecycle": {
          "name": "expirar-logs-datasul"
        },
        "number_of_shards": 1,
        "number_of_replicas": 0
      }
    },
    "mappings": {
      "properties": {
        "pasoe.message": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword",
              "ignore_above": 256
            }
          }
        }
      }
    }
  },
  "priority": 1
}

Exemplo:



7. No Dev Tools, vamos colar e executar o conteúdo do arquivo parse_pasoe_logs.txt para criar o Ingest Pipeline. Ele será responsável por entender as linhas de log do PASOE e distribuir em campos para simplificar a consulta e monitoramento futuros (será associado ao mecanismo de envio de dados do filebeat mais adiante):


6. 


5. &&& ingest pipeline (revisar nomenclatura dos campos), template (se precisar), ilm, filebeat, costurar tudo e teste integrado.