O  Agent (agente) é uma ferramenta utilizada em conjunto com o (server) e com o (broker) para prover escalabilidade horizontal a um ambiente formado por um agente, um broker e vários servers.

Em palavras mais simples, a funcionalidade de escalabilidade horizontal funciona da seguinte maneira:

1. O broker monitora o consumo de vários recursos utilizados pelos servers balanceados: conexões, memória, usuários, threads e cpu

2. À medida que o consumo total desses vários recursos alcançam um certo limite, o broker requisita ao agente a criação de uma nova instância de server

3. O agente cria uma nova instância de server e informa ao broker em qual porta TCP o novo server está aceitando conexões

4. O broker então incorpora o novo server às suas tabelas de balanceamento, de maneira que as novas conexões sejam distribuídas também para o server recém instanciado

O uso da escalabilidade horizontal para a alocação dinâmica de novos servers possibilita o funcionamento mais estável do sistema, pois evita que haja sobrecarga sobre os servers em operação.

A escalabilidade horizontal também funciona de maneira inversa: à medida que os servers se tornem ociosos por algum tempo, isto é, não estejam atendendo nenhuma conexão, o broker requisita que o agente desative estes servers que estão ociosos, desta maneira economizando recursos computacionais e diminuindo os custos de operação do sistema.

Requisitos

Para que esse esquema de escalabilidade funcione, algumas premissas devem ser atendidas. São elas:

• O binário do agente deve estar na mesma pasta onde se encontra o binário do server
• O server deve estar configurado para utilizar a porta multiprotocolo
• O server deve atender apenas as conexões provenientes do , isto é, outros modelos de balanceamento não devem estar configurados neste server
• O server dever estar sendo atendido via broker
• O broker deve estar configurado para utilizar o modelo de monitoramento ativo (modo padrão do )

Detalhes de configuração

O arquivo de configuração deverá possuir uma seção específica para o agente, conforme exemplo abaixo: 

Detalhes

Exemplo

[BROKER_AGENT]
enable = 1
BrokerServer = 10.172.16.31
BrokerPort = 12340
MaxServers = 10

A chave SecureConnection existe apenas a partir da versão 24.3.0.4, com uso do Broker HTTP. Se omitida ou com valor 0, indica que a conexão vai ser não-encriptada.
Se esta chave tiver valor 1, também deverão ser usadas as chaves de encriptação na configuração do Broker HTTP: SSL_KEY, SSL_METHOD,  SSL_CERTIFICATE.

Configuração do Server

A configuração do server depende apenas duas configurações. São elas:

1. Deve haver a seção BROKER_AGENT (como descrito acima), pois o agente e o server compartilham o mesmo arquivo de configuração (appserver.ini)
2. Deve possuir apenas a especificação da porta multiprotocolo, ou seja, não pode haver configuração de nenhuma outra seção que implique a utilização de portas TCP para outros modelos de serviço (exemplo: webapp, http, telnet)

Configuração do Broker

Para que o broker funcione no esquema de escalabilidade tratado neste material, deve ser utilizado um arquivo de configuração semelhante ao apresentado no exemplo abaixo:

Detalhes

Obs. inicialmente não se aconselha que sejam alterados os valores padrão para as chaves SCALING_LOAD_FACTOR_OUT, SCALING_LOAD_FACTOR_IN, e SCALING_GRACE_TIME. Inclusive, estas chaves nem precisam ser especificadas, vão ficar com o valor padrão. À medida que se ganhe experiência com o agente poderiam ser feitas alterações nestas chaves, entretanto sempre testando antes, para se ter noção de como essas alterações irão afetar o funcionamento do agente e do broker.

Exemplo

[BALANCE_SMART_CLIENT_DESKTOP]
LOCAL_SERVER = 12340
WITH_BROKER_AGENT = 1
SCALING_PLANS = COMERCIAL,NOITE
; SCALING_LOAD_FACTOR_OUT = 80
; SCALING_LOAD_FACTOR_IN = 60
; SCALING_GRACE_TIME = 300

; especificação dos planos de escalabilidade
; ...
; ...

* Mais detalhes sobre as chaves para especificação dos planos de escalabilidade na seção Plano de Escalabilidade

Plano de Escalabilidade

Obs. a partir da versão 20.3.1.4 do broker a consistência dos planos de escalabilidade é mais completa:

1. Todos os dias da semana precisam ter planos de escalabilidade.
2. Todas as horas do dia precisam ter plano de escalabilidade.
3. A hora final dos planos que terminam à meia noite deve ser 24:00.
4. Para os períodos em que não haverá atividade devem ser especificados MIN_SERVERS=0 e MAX_SERVERS=0.

Detalhes de Funcionamento

Por padrão, o plano de escalabilidade é aplicado uma vez por minuto.

Inicialmente apenas o broker e o agente devem estar ativos. Não importa a ordem de ativação. Nenhum server deve estar ativo.

A cada um minuto o broker faz uma checagem do plano de escalabilidade em operação, levando em consideração os critérios (detalhes na tabela acima) que foram utilizados para a configuração do plano de escalabilidade.

Caso o valor total agregado alcance ou ultrapasse 80% do valor total máximo configurado para o critério em avaliação, o broker vai solicitar ao agente que um um novo server seja instanciado, desde que o número total de servers instanciados ainda esteja abaixo do limite especificado.

Para facilitar o entendimento dos critérios para ativar/desativar um server, utilizaremos o exemplo abaixo como base:

SCALING_PLANS = Dia, Noite, FDS-Dia, FDS-Noite

    ; weekdays
    ; 1 domingo, 2 segunda, ..., 7 sabado

    ; dias de semana das 08:00 à meia noite (24:00)
    [DIA]
    FROM = 08:00
    TO = 24:00
    WEEKDAYS = 2 3 4 5 6
    MIN_SERVERS = 2
    MAX_SERVERS = 4
    CONNECTION_LIMIT = 10

    ; dias de semana das 00:00 às 08:00
    [NOITE]
    FROM = 00:00
    TO = 08:00
    WEEKDAYS = 2 3 4 5 6
    MIN_SERVERS = 1
    MAX_SERVERS = 2
    CONNECTION_LIMIT = 3

    ; fim de semana das 08:00 à meia noite (24:00)
    [FDS-DIA]
    FROM = 08:00
    TO = 24:00
    WEEKDAYS = 1 7
    MIN_SERVERS = 1
    MAX_SERVERS = 2
    CONNECTION_LIMIT = 3

    ; FIM DE SEMANA DAS 00:00 às 08:00: SEM ATIVIDADE
    [FDS-NOITE]
    FROM = 00:00
    TO = 08:00
    WEEKDAYS = 1 7
    MIN_SERVERS = 0
    MAX_SERVERS = 0
    CONNECTION_LIMIT = 3

Ativação de Novo Server no plano DIA

• Inicialmente o broker vai solicitar ao agente que instancie 2 servers, pois este foi o número mínimo configurado.
• Com  estes 2 servers iniciados, o total máximo de conexões é 20 (2 x 10).
• Aplicando o fator de carga de 80% chegamos a 16 conexões.
• O broker então vai direcionando conexões para os 2 servers de maneira balanceada.
• Quando número total de conexões chegar a 16, o broker solicita ao agente a ativação de um novo server.
• Após o novo server entrar no ar, o novo número total máximo de conexões será 30, e aplicando o fator de carga de 80%, chegamos a 24 conexões.
• O broker agora vai direcionar as conexões para os 3 servers ativos de maneira balanceada.
• Quando número total de conexões chegar a 24, o broker solicita ao agente a ativação de um novo server.
• Após o novo server entrar no ar, o novo número total máximo de conexões será 40, e aplicando o fator de carga de 80%, chegamos a 32 conexões.
• O broker agora vai direcionar as conexões para os 4 servers ativos de maneira balanceada.
• Dessa vez, quando número total de conexões chegar a 32, nenhuma ação de escalabilidade será adotada, pois o número de servers ativos vai estar no limite máximo configurado.
• Assim, o broker vai continuar direcionando conexões para os 4 servers de maneira balanceada, até que cada server esteja atendendo 10 conexões, respeitando o limite máximo configurado.
• A partir desse momento, todas as novas conexões que chegarem no broker serão recusadas.

Desativação de um Server Ocioso

• A cada vez que uma conexão for encerrada pelo client, o broker verifica se o server chegou a 0 (zero) conexões, neste caso caracterizando-o como "ocioso", e o broker marca a hora que o server entrou neste estado.
• A cada ciclo de verificação (1 vez por minuto), o broker avalia se existe algum server que está ocioso há 5 minutos (valor padrão) ou mais.
• Se o número de servers ativos está acima do mínimo configurado, o broker faz o cálculo do fator de carga para desativação, a fim de verificar se pode solicitar a desativação do server.
• No cenário acima, supondo 4 servers ativos, o broker vai pedir a desativação de um server ocioso há 5 minutos ou mais caso o número de conexões atuais seja de 18 ou menos, porque o fator de desativação para 4 servers é 60% do número máximo de conexões para 3 servers (60% de 30 conexões, que é igual a 18 conexões).

Informações adicionais

• O mesmo fluxo de ativação e desativação de servers que foi demonstrado acima, é considerando para os demais critério caso estes tenham sido configurados.
• Para a ativação de um novo server, qualquer um dos critérios configurados que atinja o fator de carga de 80% dispara a ativação de um novo server.
• Para a desativação de um server ocioso, todos os critérios configurados devem satisfazer o fator de carga de 60% para que o server seja desativado.
• Para cada server ativado, o arquivo de log (normalmente "console.log") terá o nome "worker_AAMMDD_HHMMSS_SS.log", e será gravado na pasta "worker_logs" dentro da pasta onde estão os binários do agente e do server.
• O nome da pasta "worker_logs" pode ser alterado através da chave "ConsolePath".
• O agente cria um log de nome ag_AAMMDD_HHMMSS.txt.
• O agente cria um arquivo de controle AG_CONTROL.TXT na pasta onde estão os binários do agente e do server. Em princípio este arquivo não deve ser removido mas, caso ocorra sua remoção, um novo arquivo será recriado na próxima execução do agente.

Utilização do Agente em modo interativo

Para utilizar o agente em modo interativo (isto é, rodando no terminal) passar o parâmetro "-d" na linha de comando:

              c:\pasta_agente> broker_agent -d

Caso não seja passado nenhum parâmetro na linha de comando, o agente mostra uma mensagem informativa:

              c:\pasta)_agente> broker_agent
*
* Broker Agent vrs-20.3.1.12 rev-39398 - Jul 14 2023
* (c) TOTVS S.A 2021-2023
*
* fatal error, missing run type parameter
*
* Usage:
*
*   broker_agent -desktop
*   broker_agent -install
(etc)

Parâmetros Opcionais:

Utilização do Agente como Serviço Windows

O agente pode ser utilizado como um serviço Windows.

1. Instalação do serviço:
   broker_agent -install
   
   
2. ativação do serviço:
   broker_agent -start (ou através da interface gráfica do Windows)
   
   
3. desativação do serviço:
   broker_agent -stop (ou através da interface gráfica do Windows)
   
   
4. desinstalação do serviço:
   broker_agent -uninstall

O nome do serviço vai ser BROKER_AGENT_SERVICE-(nome completo da pasta onde está o binário do agente).

Por exemplo, para a pasta D:\TOTVS\erp\12.1.33\tec\appserver-20.3.1.0-1, nome do serviço será

              BROKER_AGENT_SERVICE-D:@TOTVS@erp@12.1.33@tec@appserver-20.3.1.0-1

(as barras invertidas "\" são substituídas por arroba "@").

Obs.: No momento não existe suporte nativo para o agente ser executado como um serviço no Linux. O usuário deve criar um script ou unit do SystemD para usar o agente como serviço.