Histórico da Página
| Índice |
|---|
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.
| Informações |
|---|
Antes de continuar, veja neste link como o processo funciona: Consulta logs Datasul com Elasticsearch |
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:
|
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 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. Vamos usar a abordagem mais simples possível, sem autenticação https (apenas http), visto que todo o escopo fica concentrado na máquina dedicada, sem conexão com o mundo externo. O cliente fica livre para configurar segurança mais avançada, que não será tratada neste documento (consultar a documentação oficial).
15. 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. Yml segue o mesmo padrão do python):Atenção especial para estes campos:
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: true # exigir usuário e senha para os outros componentes (kibana e filebeat) conectarem ao banco xpack.security.enrollment.enabled: false xpack.security.http.ssl: xpack.security.transport.ssl: |
|---|
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:
26. Habilitar e iniciar o serviço:
| sudo systemctl enable --now elasticsearch |
|---|
37. 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 |
|---|
48. 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):
59. Agora vamos criar o usuário 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:
610. 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çãoAgora 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 2. 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):
| sudo systemctl enable --now kibana |
|---|
34. No navegador, acesse http://<servidor|IP>:porta/. Exemplo:
Vamos fazer login com o usuário kibana_admin, que criamos logo acima:
45. A partir deste ponto vamos concentrar as ações na janela Dev Tools:
56. 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 |
|---|
Exemplo:
67. 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 520 |
|---|
Exemplo:
78. Agora vamos criar o Ingest Pipeline 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:
89. Agora vamos criar o usuário usuário filebeat, que será utilizado em seguida para que o serviço do Filebeat consiga conectar à api do Elasticsearch com permissões para enviar novos dados.
No Dev Tools, colar e executar o comando abaixo, informando a sua senha desejada no lugar de <SENHA>:
POST/_security/user/filebeat |
|---|
Exemplo:
Filebeat
Neste momento já temos o Elasticsearch (banco de dados) e o Kibana (interface gráfica) configurados, prontos para receber logs do PASOE já no formato desejado. Na sequência, vamos instalar o filebeat, que irá monitorar os logs desejados e enviar em tempo real para o banco de dados.
| Informações |
|---|
A documentação oficial sugere que o filebeat seja instalado na mesma máquina onde os logs são gerados (no nosso caso, máquina do PASOE), e enviar os dados via rede para a máquina do Elasticsearch. Para a realidade do Datasul entendemos que esta não é a melhor abordagem, pois conforme já mencionado, optamos por isolar todos os novos processos em uma VM apartada, sem afetar a estrutura já existente para o Datasul. Portanto, nesta configuração estamos propondo a instalação do Filebeat na mesma máquina dedicada ao Elastic Stack, buscando os logs da máquina do PASOE via compartilhamento de rede. |
1. Instalar o filebeat:
| sudo dnf install -y filebeat |
|---|
Exemplo:
Configuração e utilização
12. Antes de prosseguir, garanta que a sua VM do Elastic Stack consegue ler os logs do PASOE pela rede.
Exemplo:
Aqui internamente mapeamos a pasta no /etc/fstab:
| Informações |
|---|
No nosso cenário interno foi necessário:
|
Validação do acesso aos logs originais via rede:
23. Agora vamos editar as configurações no arquivo /etc/filebeat/filebeat.yml. Este arquivo é um pouco mais complicado que os demais, vamos explicar por partes. Reforçando, tenha atenção redobrada com a identação:
3.1. Configuração dos logs do PASOE a serem monitorados e enviados para o Elasticsearch:
filebeat.inputs: - type: filestream id: datasul_squad_120 enabled: true paths: fields_under_root: true encoding: iso-8859-1 |
|---|
No exemplo acima estamos monitorando um log chamado datasul_squad_120.log. Estamos usando o mesmo nome para os campos id e environment, para simplificar a configuração. Você poderá usar nomes como DESENVOLVIMENTO, HOMOLOGAÇÃO, PRODUÇÃO, etc.
3.2. Agora vamos comentar (ou remover) os parâmetros default referentes a módulos nativos do filebeat, visto que não existe módulo pronto para o template do PASOE, e utilizaremos um criado por nós.
Vamos também adicionar a propriedade setup.template.enable: false, justamente para o filebeat não tentar criar um template automaticamente, e respeitar o nosso:
#filebeat.config.modules: #path: ${path.config}/modules.d/*.yml #reload.enabled: false #setup.template.settings: # index.number_of_shards: 1 setup.template.enabled: false |
|---|
3.3. Agora vamos configurar o envio de dados para o Elasticsearch:
output.elasticsearch: hosts: ["localhost:9200"] index: "pasoe-logs-%{[environment]}-%{+yyyy.MM.dd}" pipeline: parse_pasoe_logs preset: balanced username: "filebeat" password: "filebeat" |
|---|
No exemplo acima o Elasticsearch está na mesma máquina que o Filebeat, e na porta default, portanto mantemos o valor localhost:9200.
No campo index estamos definindo o template para a nomenclatura dos dados quer serão criados no Elasticsearch, que será: sempre começar com pasoe-logs-, seguido do nome do ambiente (variável que tratamos acima) e a data. Se você optar por mudar este padrão, terá que replicar a mudança em todas as configurações explicadas mais adiante.
No pipeline informamos parse_pasoe_logs, que é o identificador do pipeline de ingestão de dados que já criamos.
No username e password informamos as credenciais que criamos anteriormente para o Filebeat conseguir conectar à api do Elasticsearch com permissões para criação de dados.
3.4. Ao final do arquivo, vamos adicionar as configurações para geração de logs, que serão úteis em caso de problemas:
| logging.level: info logging.to_files: true logging.files: path: /var/log/filebeat name: filebeat keepfiles: 7 permissions: 0644 |
|---|
4. Agora que a configuração está concluída, vamos habilitar e inicializar o serviço, que irá começar a enviar imediatamente dados para o Elasticsearch:
sudo systemctl enable --now filebeat |
|---|
5. Se o log do PASOE estiver sendo movimentado, em alguns segundos já será possível verificar a criação do indice pela tela Dev Tools:
get_cat/indices |
|---|
Exemplo:
6. Confirmação que o indice criado respeitou o template e IML desejados:
GET/pasoe-logs-datasul_squad_120-2025.02.06/_settings |
|---|
O ILM é configurado no template. Visto que o indice reconheceu o nome correto da política de IML, a configuração está correta:
Configurar a visualização dos dados no Kibana
Agora que os dados já estão sendo gravados no banco de dados, vamos configurar a interface gráfica para visualização dos logs.
Entrar na tela Discover e selecionar a opção Create data view:
Data View
Data View é o componente que permitirá configurar uma tela para consultar dados de um determinado log.
Se você configurar o processo para tratar logs de mais de um ambiente, por exemplo, desenvolvimento, homologação e produção, então você criará um Data View para cada ambiente:
No exemplo acima, o name do Data View é SQUAD_120_DATASUL, mas poderia ser por exemplo DESENVOLVIMENTO, HOMOLOGAÇÃO, PRODUÇÃO, etc.
No campo Index pattern tenha atenção para colocar o prefixo correto do log desejado, deixando * no final. Isso fará com que ele reconheça automaticamente os novos indices que serão gerados diariamente com um nome novo, contendo a data, e consiga mostrar de forma consolidada. Veja que na medida em que você vai digitando, a tela vai filtrando na parte direita os indices reconhecidos pelo padrão definido.
| Informações |
|---|
Indice (ou index) é o conceito que o Elastic Stack utiliza para identificar um contexto dentro do banco de dados. Podemos interpretar que cada indice é uma tabela do banco, que possui dados referentes a uma fonte pré-definida, no caso, o log PASOE do ambiente desejado. |
Mantenha timestamp field com o valor default "@timestamp".
Agora que o Data View está configurado, a tela já está exibindo os dados dos logs em um formato padrão, que iremos refinar a seguir:
Vamos configurar as colunas para melhor interpretarmos os logs do PASOE. Isso não é uma regra fixa, você pode editar como preferir. Este é o modelo que utilizamos internamente:
Use o campo de pesquisa para encontrar os campos desejados, que vão aparecendo na lista da direita na medida em que são selecionados.
Campos recomendados:
- @timestamp: campo fixo e obrigatório, não pode ser retirado
- pasoe.pid: Process ID do processo do PASOE no Sistema Operacional
- pasoe.tid: Thread ID da sessão
- pasoe.writer: componente do PASOE que escreveu a mensagem
- pasoe.message: texto da mensagem
Explore os recursos de configuração da tela para tornar a visibilidade mais aderente à sua necessidade:
Salve a sua configuração com um nome significativo, para não precisar repetir os passos acima no próximo acesso:
Para finalizar, recomenda-se criar um usuário com permissões restritas à consulta, para possibilitar aos times utilizarem a ferramenta sem riscos de perda de configurações.
Entre na opção Stack Management:
Vamos criar uma role (privilégio) restrita apenas à consulta de logs.
entre na opção Roles e Create role:
Aqui chamei a role de consulta:
Mais abaixo na permissão do Elasticsearch, informei apenas * (asterisco) no padrão de índices, para garantir acesso a todos, e read no campo Privileges:
Abaixo, na permissão do Kibana, clicar em Assign to space:
No cenário atual temos apenas a Space Default (space é um conceito que não vamos abordar neste manual. Consulte a documentação oficial do Kibana se desejar criar spaces para diferenciar tipos de consulta, níveis de acesso, etc).
Associar a space Default, e abaixo habilitar Read apenas para a opção Analytics / Discover, deixando todo o restante desativado:
Agora que a role está criada, entre no menu Users e solicite para criar um novo usuário:
No exemplo, o usuário se chama consulta, e recebe apenas o priviégio (role) consulta:
Recomenda-se também alterar o campo defaultRoute nas Advanced Settings, informando /app/discover. Com isso, ao fazer novo login o usuário será direcionado automaticamente para a tela de consulta de logs, reduzindo dúvidas:
Agora, ao logar com o usuário consulta, os menus administrativos e opções de alteração de configurações não ficam disponíveis:
Exemplos de utilização
| Informações |
|---|
Consulte neste link casos de utilização da ferramenta: Consulta logs Datasul com Elasticsearch |
Visão Geral
Import HTML Content
Conteúdo das Ferramentas