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. Agora vamos criar a política de ILM (Index Lifecycle Management) expirar-logs-datasul. Ela é responsável por controlar o ciclo de vida dos dados inseridos no Elasticsearch, garantindo que os logs antigos sejam eliminados automaticamente, sem estourar o disco. O exemplo abaixo mantém os logs em estado hot no primeiro dia (usa mais recursos para acelerar as consultas), muda para cold no segundo dia (usa menos recursos de máquina, podendo aumentar o tempo de resposta das consultas) e elimina fisicamente (delete) no sétimo dia. Você pode editar estes valores e usar outras configurações mais avançadas (ver documentação oficial) se desejar guardar os logs por mais dias, ter resposta mais ágil nas consultas, etc.

Cole (edite se necessário) e execute o comando abaixo no Dev Tools:

PUT _ilm/policy/expirar-logs-datasul
{
  "policy": {
    "phases": {
      "hot": {
        "min_age": "0ms",
        "actions": {
          "set_priority": {
            "priority": 100
          }
        }
      },
      "cold": {
        "min_age": "1d",
        "actions": {
          "set_priority": {
            "priority": 50
          }
        }
      },
      "delete": {
        "min_age": "7d",
        "actions": {
          "delete": {
            "delete_searchable_snapshot": true
          }
        }
      }
    }
  }
}

Exemplo:


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 expirar-logs-datasul, 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. Agora vamos criar o Ingest Pipeline parse_pasoe_logs. 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):

No Dev Tools, vamos colar e executar o conteúdo do arquivo parse_pasoe_logs.txt:



Filebeat

Instalação




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