Manage

Interface de configuração do servidor Engine.

O Manage é uma interface web de configuração e monitoramento que pode ser acessada em qualquer servidor Engine em execução utilizando a URL “<endereço_servidor>/manage”.

Ao acessar o Manage, serão solicitados um nome de usuário e uma senha. Por padrão, o usuário e a senha são “iengine”. Essa senha padrão deve ser alterada no primeiro acesso por meio do botão “Change password” do usuário “Administrator”, exibido na aba “General” do menu “Configuration”.

Além do administrador, pode ser configurado um usuário visitante, identificado como “Guest”. Esse usuário tem acesso às opções de monitoramento, mas não ao menu “Configuration”. Por padrão, o visitante não possui senha e não pode entrar no Manage até que uma senha seja definida. A alteração do nome ou da senha de um usuário encerra todas as sessões desse usuário no Manage, sendo necessário entrar novamente.

O acesso ao Manage é mantido enquanto a aba do navegador estiver aberta e é encerrado após 15 minutos de inatividade ou por meio do botão “Sign out”, exibido na barra superior. As tentativas de login com uma senha inválida são registradas no log principal do Engine.

As configurações e informações de monitoramento apresentadas no Manage dizem respeito apenas à instância do Engine acessada. Uma visão simplificada e consolidada de todos os Engines em execução pode ser obtida por meio do processo “Administração do sistema > Monitoramento > Engines”.

Quando os Engines são acessados por meio de um balanceador de carga, ele deve ser configurado com afinidade de sessão, por cookie ou por endereço IP, para que as requisições do Manage sejam sempre atendidas pela mesma instância. Sem ela, o acesso ao Manage é perdido quando uma requisição é atendida por uma instância diferente daquela em que o login foi realizado.

Interface

As opções do Manage são acessadas pelo menu exibido ao clicar no botão à esquerda da barra superior. Em telas largas, o menu pode ser fixado na lateral da página por meio do botão “Pin menu”, exibido no próprio menu. A barra superior também exibe o usuário conectado, o botão de alternância entre os temas claro e escuro e o botão “Sign out”. Inicialmente, o tema acompanha a preferência do sistema operacional e, após ser alterado pelo usuário, a escolha fica salva no navegador.

As páginas de monitoramento, como “Requests”, “Sessions” e “Memory”, podem ser atualizadas automaticamente em intervalos de 5 segundos a 1 minuto, configurados no seletor exibido no topo da página. As listas de requisições e de sessões podem ser filtradas por qualquer texto exibido e ordenadas clicando no título das colunas. Ao clicar em uma linha, ela é expandida, exibindo os demais detalhes e as ações disponíveis. A linha expandida, a ordenação, o filtro e a posição de rolagem são preservados durante as atualizações e ao recarregar a página.

O Manage é compatível com as versões atuais dos navegadores Chrome, Edge e Firefox.

Overview

Exibe a versão, o identificador da instância, a data de início e o tempo de execução do Engine, assim como o sistema operacional e a arquitetura do servidor.

Requests

Exibe em tempo real as requisições HTTP que estão sendo atendidas pelo Engine. A opção “Profiler enabled” deve estar ativa na aba “General” do menu “Configuration” para que sejam exibidos detalhes técnicos relevantes das requisições em execução.

As requisições HTTP podem ser dos usuários utilizando navegadores Web, dos Engines utilizando o protocolo IAP sobre HTTP ou de outros sistemas que estejam consumindo APIs HTTP. No topo da página são exibidas as quantidades de requisições ativas, de tratadores e de sockets inativos, assim como a memória virtual em uso pelo Engine. As colunas exibidas são:

ID / Thread: identificador interno da conexão e da thread utilizada para tratar a requisição.
Running: tempo de execução do tratamento da requisição.
User: nome e chave do usuário responsável pela requisição.
Client: endereço IP do cliente final da requisição, normalmente o navegador do usuário. Quando há elementos intermediários, como balanceadores de carga e servidores proxy, o endereço é obtido dos cabeçalhos HTTP “X-Forwarded-For” ou “Forwarded”, conforme descrito no manual de proxies confiáveis . Os endereços de loopback (127.0.0.1 ou ::1) são substituídos pelo endereço do elemento seguinte da cadeia ou, quando o cliente é executado no próprio computador do Engine, pelo endereço principal desse computador, o mesmo retornado por engine.localAddress. Nas requisições IAP, é o endereço do cliente final informado pelo Engine que originou a requisição. Esse endereço é informado pelo cliente e não deve ser utilizado para fins de validação de segurança. Ao clicar no endereço, é exibido um diálogo com os detalhes da origem da requisição, descritos abaixo.
Database: quando a requisição realiza consultas ao banco de dados, essa coluna exibe o nome da base de dados.
DB SID: quando a requisição realiza consultas ao banco de dados, essa coluna exibe o identificador da conexão no SGBD. Essa informação pode ser utilizada pelo administrador para consultar detalhes técnicos no SGBD.
Workload: indica qual o tipo de comportamento configurado na aplicação no momento daquela requisição. Valores possíveis:
- olap (Online analytical processing): indicado para relatórios ou processos de consulta. Normalmente, interagem com uma massa de dados média ou elevada. Prioridade de atendimento média;
- oltp (Online transaction processing): indicado para processos que realizam a leitura ou gravação de poucos registros. Prioridade de atendimento alta;
- dw (Data Warehouse): indicado para processos que consolidam grandes massas de dados para pesquisas posteriores. Prioridade de atendimento baixa;
Status: mensagem que o sistema atribui à requisição, identificando a que se refere.
Referrer: identificador do processo ou página que originou a requisição.

Ao expandir uma requisição, são exibidos o status e o referrer completos, o status do profiler, os elementos intermediários por onde a requisição passou, os identificadores da sessão e do Engine de origem e a data de início do atendimento. Também são exibidos os botões “Origin details”, “Profile” e “Abort”, que permitem consultar os detalhes da origem da requisição, obter detalhes técnicos sobre a execução, para fins de análise de desempenho, e interromper a requisição em atendimento. A interrupção de uma requisição pode não ser imediata, pois o sistema pode estar bloqueado aguardando a finalização de comandos enviados para sistemas de terceiros ou bibliotecas nativas externas.

O diálogo de detalhes da origem da requisição, exibido ao clicar no cliente ou no botão “Origin details”, apresenta:

Client: exibe o endereço do cliente e, quando houver, os elementos intermediários por onde a requisição passou (Forwarded by), do mais próximo ao mais distante do Engine, como balanceadores de carga e servidores proxy. Nas requisições IAP, o Engine de origem não é considerado um elemento intermediário, pois ele realiza uma nova requisição para atender a do seu cliente, e é exibido na seção Engine.
Session: sessão de origem da requisição. Nas requisições HTTP, é a sessão que atende a requisição. Nas requisições IAP, é a sessão do cliente que originou a requisição, e não a sessão temporária eventualmente criada para atendê-la. Exibe informações como o usuário, o realm, o endereço e o navegador do cliente e o tipo da sessão: stateful, stateless ou standalone. As informações das sessões do próprio Engine são obtidas em tempo real e estão disponíveis para todos os tipos de sessão. Já as sessões de outros Engines são consultadas na tabela de monitoramento de sessões, exibida no processo “Administração do sistema > Monitoramento > Sessões de aplicativos”, onde são registradas apenas as sessões de aplicativos, que são sempre stateful. Para as demais sessões de outros Engines, como as utilizadas por APIs HTTP, scripts agendados ou execuções remotas, é exibido apenas o identificador. As informações também não estarão disponíveis se a sessão já tiver sido encerrada.
Engine: indica que a requisição foi originada no próprio Engine ou, nas requisições originadas por outros Engines, exibe o nome, o endereço IP, a porta, a versão e o tipo de servidor do Engine de origem, consultados na tabela de monitoramento dos Engines.

Sessions

Relação das sessões JavaScript criadas no servidor. No topo da página são exibidas as quantidades de sessões de cada tipo e das sessões em uso. As colunas exibidas são:

Realm: o “realm” de uma sessão determina as características comuns das sessões que atendem uma determinada aplicação, como a preservação do estado (stateful ou stateless), tempo de vida e de inatividade. Um realm pode ser associado a um caminho da Virtual File System ou a um conjunto de rotas HTTP. Sessões de um “realm” são isoladas das demais, garantindo que as aplicações distintas não compartilhem informações de usuários. Os realms são configurados no diretório “/Configurações/Realms” e o realm “wf-data” é o mais comum, pois é o utilizado pelas sessões de usuários do Web Framework.
Kind: as sessões podem ser de 3 tipos:
- Stateful: sessões que preservam o estado durante múltiplas execuções e que normalmente são utilizadas nas interfaces com o usuário final, como aquelas construídas utilizando o Web Framework. Devido à preservação do estado, elas normalmente consomem uma quantidade elevada de memória e deve-se evitar que haja mais de 25 sessões stateful simultâneas em um Engine.
- Stateless: sessões que não garantem a preservação do estado durante múltiplas execuções. São utilizadas pelas rotas HTTP, pelo Scheduler e para executar scripts internos do Engine.
- Standalone: sessões que não são compartilhadas e que têm um controle de vida manual. Utilizadas pela API ScriptRunner, pela IDE embarcada do Engine e por scripts de execução única.
Session ID: identificador da sessão JavaScript.
Thread: identificador da thread que está atendendo a sessão. Fica em branco quando a sessão não está em execução.
User: nome e chave do usuário responsável pela sessão.
Address: endereço IP de onde o Engine recebeu a requisição. Se o Engine estiver sendo acessado por meio de um balanceador de carga, esse IP será o do balanceador.
Created at: data e hora de criação da sessão.
Accessed at: última vez que foi processada uma requisição utilizando a sessão.
Expired: indica se a sessão encontra-se expirada e será eliminada pelo sistema na próxima rotina de limpeza do gerenciador de sessões.
Memory: memória reservada pela sessão.
DS: quantidade de DataSets ativos na sessão.

Ao expandir uma sessão, também são exibidos:

Running script ou Last script: endereço ou chave do script em execução na sessão ou, quando ela não está em uso, do último script executado. Essa informação permite identificar o código responsável pelas sessões sem realm ou sem usuário, como as criadas por scripts agendados ou pela API ScriptRunner. Ela também pode ser pesquisada no filtro da página.
Profile: perfil da sessão. Os perfis de sessões com acesso ao SGBD são nomeados com o nome da base de dados ou utilizam esse nome como sufixo.
Forwarded for: exibe o valor do cabeçalho “X-Forwarded-For” da requisição HTTP recebida. Quando o Engine é acessado por meio de um balanceador de carga, o IP da estação de origem da requisição fica registrado nesse cabeçalho HTTP.
Max inactive time: tempo máximo de inatividade da sessão em segundos.
Max life time: tempo máximo de vida da sessão em segundos. O valor 0 (zero) indicará que a sessão não tem um tempo máximo de vida configurado e a sessão será eliminada apenas se for atingido o tempo máximo de inatividade.
In use: indica se a sessão está atendendo uma requisição.

Os botões “Profile” e “Drop” permitem obter detalhes técnicos sobre as requisições atualmente em processamento na sessão e expirar a sessão de modo forçado.

Memory

Detalhes do consumo de memória do Engine e do sistema operacional do servidor. Deve-se ter atenção para que a memória consumida pelo sistema esteja sendo preferencialmente atendida pela memória física do servidor. O uso de memória paginada em disco prejudica de forma significativa o desempenho do sistema, principalmente em ambientes em nuvem onde o disco é um storage externo.

Caso ainda esteja sendo utilizada a versão 32 bits do Engine, deve-se ter cuidado do consumo de memória não ultrapassar o limite imposto pelo sistema operacional de 3GB ou 4GB. Ao atingir esse limite, o Engine poderá ser interrompido de forma forçada, podendo provocar a corrupção do cache local. Esse limite não existe na arquitetura 64 bits e, por esse motivo, a versão 32 bits não deve ser mais utilizada.

A página exibe gráficos com a evolução da memória virtual em uso, da memória física disponível e da quantidade de sessões de cada tipo, que podem ser consultados na última hora, nas últimas 24 horas, nos últimos 7 ou nos últimos 30 dias. Abaixo dos gráficos, são exibidas as informações atuais:

Process: memória utilizada pelo processo do Engine.
- Virtual memory: memória virtual que de fato está sendo utilizada pelo Engine e o valor máximo já requisitado ao sistema operacional (peak). Este valor desconsidera a memória virtual reservada para as bibliotecas compartilhadas e as páginas de memória que foram reservadas, mas que não foram confirmadas. No Windows, é considerada memória virtual em uso o tamanho de confirmação do processo (commit charge) e, no Linux, a soma da memória residente e da paginada em disco (RSS + Swap).
- Physical memory: quantidade de memória física do sistema operacional utilizada pelo Engine e o valor máximo já utilizado (peak). No Windows, será igual ao conjunto de trabalho do processo (working set) e essa métrica pode incluir memória de bibliotecas compartilhadas com outros processos. Por esse motivo, o seu valor pode ser superior à memória virtual em uso. No Linux, será apresentado o tamanho da memória residente (RSS).
- IDO cache: quantidade de memória reservada para cache do banco de dados IDO, utilizado pelos DataSets temporários e pelo cache local da base de dados.
Server: memória do sistema operacional.
- Physical memory: memória física em uso e o seu tamanho total.
- Page file: memória em uso e o tamanho total do arquivo de paginação do sistema operacional. No Windows, o tamanho do arquivo de paginação também considera a memória física. No Linux, essa informação é relativa apenas ao tamanho do Swap. A paginação de memória em disco pode degradar o desempenho do sistema, portanto deve-se considerar aumentar a memória física instalada caso o percentual de memória paginada em disco seja alto em relação à memória física disponível.
Sessions: quantidade das sessões por tipo.

As informações de memória apresentadas no Manage também pode ser obtidas por meio da API SystemMonitor .

Profiler

Exibe as estatísticas das operações mais lentas registradas pelo profiler do Engine, coletadas apenas quando a opção “Profiler enabled” está ativa na aba “General” do menu “Configuration”. As estatísticas podem ser descarregadas por meio do botão “Download” e descartadas por meio do botão “Clear”. Os botões “Profile” das páginas “Requests” e “Sessions” exibem nesta página os detalhes da execução atual de uma thread.

Log

Arquivos de logs gerados pelo sistema contendo informações técnicas emitidas pelo Engine, como também dos processos e relatórios executados no sistema. Em sua configuração padrão, o sistema gera os seguintes arquivos de log:

main.log: arquivo de log principal do sistema que registra as informações escritas por meio da variável global log ou por instâncias da classe Logger .
engine.log: informações relacionadas ao funcionamento do Engine, como inicialização e encerramento do sistema.
dbCache.log: informações relacionadas à inicialização e ao sincronismo do cache local do Engine.
scheduler.log: detalhes da execução dos scripts agendados pela classe Scheduler ou pelo processo “Administração do sistema> Scripts agendados > Agendador de scripts”.
profiler.log: registros de desempenho dos scripts executados no Engine, gerados apenas quando a opção “Profiler enabled” está ativa na aba “General” do menu “Configuration”. As informações contidas nesse arquivo podem ser analisadas utilizando o processo “Desenvolvimento > Profiler > Analisador de logs do Profiler”.
httpAccess.log: requisições HTTP atendidas pelo sistema. Os registros de log gerados seguem o padrão Combined Log Format e podem ser processados por ferramentas de monitoramento de acesso que suportem esse formato.
email.log: registros dos e-mails enviados pelo Engine.
sql.log: por padrão, são registradas as seguintes informações:
- Comandos DDL executados via Database.prototype.executeDDL .
- Comandos DML executados via Database.prototype.executeSQL . O comandos DML são gravados na categoria “sql.unsafe”, permitindo o tratamento customizado desses logs caso seja necessário.
- Comandos SQL enviados por conexões configuradas com workloadType do tipo 'oltp' e com duração superior ao valor da configuração MaxOltpQueryExecutionTime na aba “Configuration file” do menu “Configuration”.
- Erros na execução de comandos SQL.
supervisor.log: informações sobre o consumo de recursos do sistema, gerados de forma periódica enquanto o Engine está em execução.
java.log: registros relacionados a integração com o Java e os valores capturados da saída padrão e de erro do Java.
console.log: contém as informações escritas na saída padrão do processo do Engine. Via de regra, os logs do sistema são escritos de forma estruturada nos demais arquivos de log por meio da API Logger. No entanto, no Engine Linux, algumas mensagens são escritas diretamente na saída padrão para simplificar o uso do sistema via linha de comando. Outros aplicativos e bibliotecas de terceiros iniciadas a partir do Engine também podem escrever mensagens na saída padrão.
crash.log: registros dos encerramentos forçados que foram detectados pelo Engine.

A página “Log” relaciona os arquivos do diretório de logs, que podem ser filtrados pelo nome e descarregados individualmente ou em conjunto, compactados em um arquivo ZIP, informando a quantidade de dias dos arquivos que devem ser incluídos.

Ao clicar no nome de um arquivo, ele é aberto no visualizador de logs, que ocupa toda a página. Por padrão, são exibidos os registros mais recentes, do final do arquivo, até o tamanho máximo selecionado, de 100 KB a 50 MB. A opção “Oldest” exibe os registros mais antigos, do início do arquivo.

O campo “Search” pesquisa os registros que contêm o texto informado, destacando as ocorrências encontradas, e pode ser combinado com as opções “Match case” (diferenciar maiúsculas e minúsculas), “Match whole word” (palavra inteira) e “Use regular expression” (expressão regular na sintaxe do JavaScript). A pesquisa é realizada pelo Engine em todo o arquivo, a partir do seu final ou do seu início, conforme a opção “Newest” ou “Oldest”, e o tamanho máximo selecionado limita apenas os registros encontrados. Dessa forma, não é necessário aumentar o tamanho máximo para encontrar registros antigos em arquivos grandes. Para não ocupar o Engine por muito tempo, a pesquisa é interrompida após 30 segundos, sendo informado o quanto do arquivo foi pesquisado.

Os registros com mais de uma linha, como os que contêm a pilha de chamadas de um erro, são exibidos e pesquisados por completo, e não apenas a linha onde o texto foi encontrado. O tamanho máximo pode ser ultrapassado para completar o último registro exibido.

Para uma análise de vários arquivos de log, é recomendado que eles sejam descarregados em um computador local e sejam utilizadas ferramentas como o VS Code ou o Notepad++ para realizar a pesquisa no diretório extraído.

Configuration

O menu “Configuration” é exibido apenas para o administrador e permite alterar as configurações do Engine por meio das seguintes abas:

General: configurações gerais do Engine, agrupadas em:
- Users: nomes dos usuários “Administrator” e “Guest” do Manage, que podem ter o nome e a senha alterados por meio dos botões “Change name” e “Change password”. As alterações são salvas imediatamente.
- Sessions and tasks: limites de sessões por realm e quantidade máxima de tarefas simultâneas do Scheduler.
- Profiler: ativação do profiler e do profiler automático e o tempo mínimo de execução das operações que devem ser registradas no arquivo “profiler.log”. Mais detalhes no manual Analisador de logs do Profiler .
- JavaScript: ativação do depurador JavaScript, que requer o reinício do Engine.
- Other settings: ativação da integração com o Certbot, que requer o reinício do Engine, e caminhos permitidos para o sincronizador de arquivos.
Ports: portas HTTP e HTTPS abertas pelo Engine. Nas portas HTTPS, são exibidos logo abaixo da porta os campos do certificado digital, da chave privada, da senha da chave privada e da lista de algoritmos de criptografia aceitos. Mais detalhes no manual Configuração do HTTPS no Engine .
Domains: domínios atendidos pelo Engine e as bases de dados associadas a eles.
Databases: bases de dados que podem ser acessadas pelo Engine. O botão “Test connection” de cada base de dados verifica a configuração gravada, conectando ao banco de dados e consultando a sua data e hora. Mais detalhes no manual Bancos de dados .
Logger: configuração complementar dos arquivos de log. Ela é adicionada à configuração padrão, exibida logo abaixo, e precisa conter apenas as entradas que devem ser alteradas ou incluídas. As configurações devem ser realizadas em um formato similar ao adotado pelo log4j , sendo recomendado seguir os padrões adotados na configuração padrão do sistema.
Configuration file: conteúdo do arquivo de configuração do Engine, permitindo informar configurações avançadas não disponíveis nas demais abas. O botão “Reset to defaults” restaura os valores padrão do arquivo.

As senhas das bases de dados e das chaves privadas não são exibidas. Elas são preservadas quando não alteradas. Algumas configurações requerem que o Engine seja reiniciado. Mais detalhes sobre as configurações do Engine no manual Configuração do Engine .