--- name: azion-monitore-e-calibre-o-bot-manager description: >- Execute uma instância do Bot Manager em observação, leia as pontuações no log de report e defina threshold e regras a partir do seu próprio tráfego. --- # Monitore e calibre o Bot Manager Você calibra uma instância do [Bot Manager](/pt-br/documentacao/plataforma/firewall/#bot-manager) elevando o nível de log dela, lendo o log de report que ela escreve e definindo o threshold e as regras a partir do que esse log mostra. Os mesmos passos se aplicam ao Bot Manager e ao [Bot Manager Lite](/pt-br/documentacao/plataforma/firewall/bot-manager/bot-manager-lite/). Os argumentos que cada edição carrega são diferentes, e o procedimento não é. [Boas práticas de Firewall](/pt-br/documentacao/plataforma/firewall/boas-praticas/#bot-manager) cobre o que cada escolha custa e por quanto tempo mantê-la; esta página cobre os passos que produzem a escolha. Mude uma coisa por vez. Uma mudança de argumento alcança o caminho da requisição em cerca de dois minutos, então uma leitura feita antes disso descreve a configuração que a precedeu. --- ## Pré-requisitos - Uma instância de função do Bot Manager em um firewall, executada por uma regra do [Rules Engine for Firewall](/pt-br/documentacao/plataforma/firewall/rules-engine/). Para mais informações, consulte [Primeiros passos com Bot Manager](/pt-br/documentacao/plataforma/firewall/bot-manager/primeiros-passos/). - Acesso ao Azion Console. Para entrar, consulte [Como acessar o Azion Console](/pt-br/documentacao/guias/plataforma/conta-e-billing/como-acessar-o-azion-console/). - Um personal token, para a consulta que lê o log de report. Para mais informações, consulte [Personal Tokens](/pt-br/documentacao/fundamentos/personal-tokens/). --- ## Eleve o nível de log Uma instância escreve uma linha de report para as requisições que `internal_logs` seleciona, e o argumento é entregue em `0`. Eleve-o para `2` para que toda requisição produza uma linha, inclusive uma que pontue `0`, e defina `action` como `allow` para que uma requisição que alcança o threshold seja pontuada e ainda assim atendida. ```json { "threshold": 30, "action": "allow", "internal_logs": 2, "log_tag": "bot-calibration", "log_headers": [ "accept", "accept-encoding", "accept-language", "content-type", "host", "referer", "user-agent", "x-forwarded-for", "x-request-id" ] } ``` | Argumento | O que ele faz na janela de observação | | --------------- | ------------------------------------------------------------------------------------------------ | | `action` | Em `allow`, uma requisição igual ou acima do threshold segue para a aplicação | | `internal_logs` | Em `2`, a função escreve uma linha para toda requisição. O valor é um número, nunca uma string | | `log_tag` | A tag que o prefixo da linha carrega, que é o que separa as linhas de uma instância das de outra | | `log_headers` | Os cabeçalhos de requisição que a função escreve na linha. Os nove acima são o padrão entregue | > **Atenção** > > Nada valida o objeto de argumentos. Uma chave com erro de digitação, como `thresold`, é armazenada e lida de volta exatamente como foi digitada, a função roda no padrão dela e nenhuma interface devolve erro. Para substituir os argumentos de uma instância existente no Azion Console: 1. **Abra o firewall que executa a instância** Acesse o [Azion Console](https://console.azion.com/) > **Firewalls** e selecione esse firewall. 2. **Selecione a aba Functions Instances** 3. **Abra a instância** Selecione a instância do Bot Manager que você quer calibrar. 4. **Substitua os argumentos** Na seção **Arguments**, informe o objeto. O Bot Manager Lite não carrega schema de argumentos, então a seção traz um editor JSON e não constrói formulário a partir dele. 5. **Salve a instância** A instância pontua toda requisição que a regra envia a ela e não recusa nenhuma. Espere cerca de dois minutos antes de tirar qualquer conclusão de uma resposta, e mantenha a janela aberta por tempo suficiente para cobrir horários de pico, crawlers semanais e jobs noturnos. Para saber quanto tempo é esse e o que ele custa, consulte [Boas práticas de Firewall](/pt-br/documentacao/plataforma/firewall/boas-praticas/#bot-manager). --- ## Leia o log de report no Real-Time Events O [Real-Time Events](/pt-br/documentacao/plataforma/real-time-events/) entrega cada linha de report como um registro do dataset `functionConsoleEvents`. No Azion Console esses registros são renderizados em uma coluna **Time** e uma coluna **Log Body**, e a interface não carrega nenhum campo próprio do Bot Manager: o objeto JSON chega inteiro, em vez de dividido em colunas que você possa ordenar. Estreite o período para a janela que você rodou e leia as linhas cujo prefixo carrega o seu `log_tag`. Para ler os mesmos registros como uma consulta, envie o seguinte para `https://api.azion.com/v4/events/graphql`, com um cabeçalho `Authorization: Token [TOKEN VALUE]` e um `tsRange` que cubra a janela: ```graphql { functionConsoleEvents( limit: 200 filter: { tsRange: { begin: "2026-01-01T11:30:00", end: "2026-01-01T13:00:00" } } orderBy: [ts_ASC] ) { ts line level lineSource functionId configurationId } } ``` A consulta responde `200` e devolve um registro por linha que a função escreveu. `line` carrega a linha de report inteira, `functionId` é o id da função instalada, e `configurationId` é o id do workload em que a requisição chegou, não o id do firewall em que a instância é executada. Uma linha abre com o prefixo `[Bot-Protection][] Report:` e continua como um único objeto JSON: ```text [Bot-Protection][bot-calibration] Report: {"request_id":"0123456789abcdef0123456789abcdef","remote_addr":"203.0.113.42","fingerprint":"ge20cn020000_000000000000_000000000000_000000000000","host":"","http_user_agent":"","request_uri":"/","geoip_country":"BR","geoip_region":"SP","asn":"64496","score":28,"bot_category":"Bad Bot Signatures, Malicious Intent detected","classified":"legitimate","action":"allow","matched_rules":[1,10,18,19,20]} ``` Quatro valores carregam a calibração. `score` é o total que a função calculou, `matched_rules` nomeia as regras que o produziram, `action` é o que a função aplicou, e `classified` é o veredito a que ela chegou. Na linha acima a pontuação é `28` sob um threshold de `30`, então `action` lê `allow` e `classified` lê `legitimate`. Sob um threshold que `28` alcança, a mesma requisição lê `bad bot` e encontra a ação configurada. `bot_category` é uma lista, unida por vírgula, das categorias das regras que a requisição correspondeu, então uma linha classificada como `legitimate` ainda pode nomear categorias de bad bot. Para cada campo que uma linha carrega e para os quatro valores que `classified` assume, consulte [Logs](/pt-br/documentacao/plataforma/firewall/bot-manager/logs/#campos). A pontuação está na linha e em nenhum outro lugar. Os dois datasets GraphQL de Real-Time Metrics contam requisições por classificação, ação, modo, host, geografia e pelas URLs que o tráfego de bots alcançou, e nenhum dos dois carrega uma pontuação, então uma distribuição de pontuações é lida do log de report, e não de uma consulta. Esses datasets respondem às perguntas agregadas: consulte [Consulte dados do Bot Manager com GraphQL](/pt-br/documentacao/guias/plataforma/observabilidade/consultar-dados-bot-manager-com-graphql/) para as contagens de classificação, [Consulte as URLs mais atingidas por bots com GraphQL](/pt-br/documentacao/guias/plataforma/observabilidade/consultar-dados-bot-manager-breakdown-com-graphql/) para as URLs, e [Real-Time Metrics](/pt-br/documentacao/plataforma/real-time-metrics/dashboards-secure/#bot-manager) para os mesmos dados em gráficos. --- ## Defina o threshold a partir das pontuações que você leu `threshold` é a pontuação em que `action` é executada. O valor vem da distribuição no seu próprio log de report: os clientes que você reconhece se agrupam na ponta baixa, os clientes automatizados se agrupam mais acima, e o threshold vai no intervalo entre os dois. Para calibrá-lo: 1. **Colete as pontuações da janela** Leia `score` nas linhas que a janela produziu e separe as requisições que você reconhece das que você não reconhece. 2. **Escolha um valor no intervalo** Defina-o acima das pontuações do tráfego que você reconhece, e igual ou abaixo das pontuações do tráfego que você não reconhece. 3. **Aplique o threshold e a ação** Substitua os argumentos da instância pelo novo `threshold` e pela `action` que uma requisição igual ou acima dele encontra. 4. **Espere cerca de dois minutos** Uma mudança em uma instância chega ao caminho das requisições em cerca de dois minutos. 5. **Leia as linhas mais próximas do threshold** Leia as linhas classificadas como `legitimate` cuja pontuação fica logo abaixo dele. Essas requisições estão a uma regra correspondida da ação. A instância aplica a ação ao tráfego acima do threshold, e as linhas abaixo dele nomeiam as requisições que chegaram mais perto. Repita o ciclo: baixe o threshold enquanto tráfego automatizado ainda passa, e eleve-o quando requisições que você reconhece forem recusadas. > **Atenção** > > `classified` é calculado contra o threshold em vigor, não contra a pontuação sozinha. Elevar um threshold reetiqueta o tráfego, além de impedir a ação, então registre o threshold ao lado de qualquer contagem de classificação que você compare entre dois períodos. `score` e `matched_rules` descrevem a requisição e não se movem. --- ## Retire uma regra da pontuação Uma pontuação é a soma dos incrementos das regras que a requisição correspondeu, e a linha nomeia as duas coisas: `matched_rules` carrega os IDs e `score` carrega o total. Uma regra que dispara em tráfego que você reconhece é encontrada lendo esses IDs. Nenhum ID entra no objeto de argumentos antes de aparecer nas suas próprias linhas. Para impedir que uma regra eleve uma pontuação: 1. **Encontre as linhas que você não esperava** Leia as linhas classificadas como `legitimate` cuja pontuação fica no threshold ou perto dele, e as linhas que carregam requisições que você reconhece. 2. **Leia os IDs das regras nessas linhas** `matched_rules` carrega os IDs das regras que cada requisição correspondeu. Compare várias linhas, para que uma requisição sozinha não decida a questão. 3. **Acrescente os IDs aos argumentos da instância** `disabled_rules` os recebe no Bot Manager Lite, e `disabled_static_rules` os recebe no Bot Manager. Os dois são arrays. 4. **Espere cerca de dois minutos e leia as linhas de novo** Uma regra desabilitada dessa forma continua rodando e não soma nada à pontuação. As requisições que correspondiam à regra pontuam menos pelo incremento dela, e cada correspondência passa a cair no campo `disabled_matched_rules`. Uma regra retirada da pontuação fica fora dela para toda requisição que a instância pontua, então vale ler antes os instrumentos mais estreitos: consulte [Boas práticas de Firewall](/pt-br/documentacao/plataforma/firewall/boas-praticas/#bot-manager). Para os dois argumentos e os tipos que eles recebem, consulte [Argumentos](/pt-br/documentacao/plataforma/firewall/bot-manager/argumentos/#campos). --- ## Eleve a tolerância das regras dinâmicas O Bot Manager documenta um método de regras dinâmicas que pontua uma requisição contra a linha de base do tráfego da própria aplicação. `dynamic_rules_tolerance` define o quanto essa comparação é estrita, e os valores documentados são `soft`, `medium` e `hard`, com `soft` como padrão documentado. Mova um passo por vez. Uma mudança de tolerância repontua toda requisição que a instância vê, então cada passo precisa de uma janela de observação própria antes do seguinte. Dois passos dados juntos produzem os seus falsos positivos juntos, sem nada nas linhas que diga qual passo os produziu. ```json { "threshold": 18, "action": "deny", "dynamic_rules_tolerance": "medium", "dynamic_rules_logs_enabled": true, "log_tag": "tolerance-medium" } ``` `dynamic_rules_logs_enabled` escreve os logs de depuração do método. Ligue-o durante a janela e desligue-o quando a janela fechar, por causa do volume que ele acrescenta ao log. Para os quatro argumentos que o método recebe, consulte [Argumentos](/pt-br/documentacao/plataforma/firewall/bot-manager/argumentos/#regras-dinamicas). --- ## Guarde uma cópia do log de report A plataforma descarta os dados agregados com o tempo. `botManagerMetrics` é retido por 2 anos e `botManagerBreakdownMetrics` por 60 dias, então uma pergunta sobre as URLs que o tráfego de bots alcançou três meses atrás não tem resposta ali. Uma cópia em um destino seu dura o quanto você a mantiver, e fica ao lado dos registros da aplicação que essas requisições alcançaram. O [Data Stream](/pt-br/documentacao/plataforma/data-stream/) encaminha a linha de report da data source Functions para um endpoint que você configura, no momento em que a função a escreve. Baixe `internal_logs` quando a janela de observação fechar: em `2` toda requisição produz uma linha, e esse é o volume que o stream carrega. Para os endpoints em que um stream escreve, consulte [Endpoints](/pt-br/documentacao/plataforma/data-stream/endpoints/). --- ## Próximos passos - [Boas práticas de Firewall](/pt-br/documentacao/plataforma/firewall/boas-praticas.md#bot-manager): O que cada uma dessas escolhas custa, e a ordem em que as decisões aparecem. - [Logs](/pt-br/documentacao/plataforma/firewall/bot-manager/logs.md): Cada campo que uma linha de report carrega, os vereditos que classified assume e onde cada log aparece. - [Solucionar problemas de Firewall](/pt-br/documentacao/plataforma/firewall/solucao-de-problemas.md#bot-manager): O que fazer quando nenhuma linha nomeia uma requisição, ou um cliente é respondido de um jeito que você não esperava. - [Argumentos](/pt-br/documentacao/plataforma/firewall/bot-manager/argumentos.md): Cada argumento que uma instância aceita, com o tipo, o padrão e os valores que ele recebe.