feat(docs): new bot manager content - #2387
Merged
marcus-souza-azion merged 3 commits intoSep 22, 2026
Merged
Conversation
The Bot Manager section was three pages written before the style guide existed. The overview carried a definition, a 14-row bot classification table, a 17-row argument table, a 26-field log dictionary and an 8-step Captcha procedure under one title. The Bot Manager Lite reference opened with a second H1 in its body. The product tree declared Quickstart and Glossary as placeholders that no page filled. Nine of the thirteen slots now hold a page: how it works, two new reference pages for arguments and logs, the rewritten Lite reference, limits, best practices, troubleshooting and a glossary. Quickstart, examples, the guides hub and the overview are still owed, as are the Portuguese pairs and the navigation entries. No permalink moved, so no redirect is owed. A run against a real account settled the facts these pages rest on and corrected several the corpus had wrong. Bot Manager is not a firewall module: the firewall has four, and Bot Manager runs as a function instance on the functions module, which is enabled by default. The rule that runs it carries a behavior keyed type, not name, whose attribute is value and holds the instance id rather than the function id. An instance name is bounded at 100 characters and its arguments payload at exactly 100,000 bytes, both found by bisection, and the payload bound is decimal rather than 100 KiB. Instances per firewall are not bounded at all: twelve on one firewall were every one accepted. Reading the installed function corrected the Lite argument table four times. internal_logs is a number, not the string the page typed. The default threshold is 30, not the 10 every Lite page used nor the 18 the overview recommended. threshold and action were marked required and neither is. log_headers is a default allowlist of nine headers the function writes, not a forbidden list. The report log was read from the functionConsoleEvents dataset and corrected six more. Its prefix carries the log tag, not the host. Bot Manager Lite writes fourteen fields where the full edition documents twenty-five, so a Lite log is not a full-edition log. Lite does emit classified and bot_category. geoip_country is a country code, matching the field table rather than the specimen beside it. The fingerprint is four underscore-separated segments, not either hex hash the corpus showed. bot_category is a comma-joined list derived from the classes of the rules that matched. Two behaviors no page had documented now appear where a reader meets them. An arguments object is not validated: every key sent is stored and returned unchanged, including one deliberately misspelled, so thresold leaves the threshold at its default with no error in any interface. And a client with no valid session receives 204 with an empty body and the two session cookies, indefinitely if it neither runs JavaScript nor keeps them, which reads as neither a block nor a success. One classification finding changes how the field should be read. classified follows the threshold rather than the score: the same score of 28 from the same matched rules returned legitimate under a threshold of 30 and bad bot under a threshold of 1. Raising a threshold relabels traffic as well as stopping the action. The published Lite rule table is confirmed correct. Two independent rule sets each sum to the measured score of 28 using the table's own increments, so the one rule catalogue the product publishes can be trusted. The full edition's static rules remain published nowhere, so no page lists, names or scores one, and the instruction to disable rule 22 does not survive; the pages teach reading matched_rules and disabling by the id the reader finds. No page states a score scale, because no source states a maximum. The billing metric named profile stays undefined and off the limits page and out of the glossary.
The section was three pages written before the style guide: a 505-line overview mixing positioning, mechanism, a 14-row classification table, a 17-row arguments table, a 26-row log-field dictionary and an 8-step challenge procedure; a Lite reference carrying a second H1 in its body; and a guides hub whose rows all read "How to ...". Two nav rows pointed at placeholders no page filled. It is now the thirteen-slot product section. New pages: quickstart, how it works, arguments, logs, limits, best practices, troubleshooting, glossary, and an examples index with four snippet pages. Rewritten in place: the overview (505 to 101 lines), Bot Manager Lite, and ten guides. Portuguese carries every page. A live run against the platform corrected the corpus rather than restating it: - Bot Manager is not a firewall module. It runs as a function instance on a firewall, and the v4 spec declares no bot_manager module. - The rule behavior is run_function with the instance id in "value" - not "name", not "function_id", and not the installed function's id. - The arguments object is unvalidated. A misspelled key is stored, echoed back byte for byte, and silently ignored while the function runs on its default. - classified follows the threshold, not the score: one score of 28 read legitimate at threshold 30 and bad bot at threshold 1. Classification counts are comparable only across an unchanged threshold. - Lite ships threshold 30 and action deny, so an instance created with an empty arguments object refuses the first request that crosses 30. Its internal_logs is the number 0, not the string "2". - Network list 2 is Azion IP Tor Exit Nodes, not Origin Shield IPs as the old guide said. - An argument change reaches the request path in about two minutes, so a re-test run immediately after one describes the arguments before it. Silent failure modes now carried by the pages: a 204 with an empty body is neither a refusal nor a pass; a Request Args criterion matching .* skips every request that has no query string; a misspelled argument is accepted by every interface with no error. Nav and links: bot-manager.json gains the Examples and Reference groups and loses both placeholder rows; guides.json retags ten rows as how-to-guide and hoists bot-manager to products[0] on two. Every permalink and namespace is frozen, so no redirect is owed, and every inbound anchor was repointed to a heading that exists. Left unwritten, and why: the full edition's static rule catalogue is published nowhere, while matched_rules hands readers its rule IDs; a billing "profile" costs $195 beyond the first and is defined in no source. Every full-edition bound stays reported rather than observed - the account used for the live run carries Lite only.
The Bot Manager rework adds 26 pages, and this check counts link issues across the whole build, so the number rose from 26,516 to 26,799 and the ratchet failed with "this branch adds 283". None of the 283 is a broken link. 26,439 of the 26,799 issues are [404]s the page template emits on every page: the footer's links into the marketing URL space, which the documentation build does not contain, and each page's own .md twin from FallbackNotice.astro. Every page in the corpus carries about 16 of them, so the count tracks how many pages exist rather than how many links are wrong. Measured on a full build of this branch: of the 856 issues on the 57 changed pages, all 856 are those two template classes, none is a link written in the rework, and none is a broken fragment. No fragment issue anywhere in the build points at a page or an anchor the rework changed. The changed pages average 15.0 issues each; the other 1,698 average 15.3. This re-snapshot unblocks the branch. It does not fix the cause: while the two template classes are counted, every pull request that adds a page fails this check and re-snapshotting is the only way past it, which is how a ratchet stops meaning anything. Excluding them belongs in its own change against scripts/lint-linkcheck.ts.
marcus-souza-azion
requested review from
bruno-andrade-azion,
isaque-bock-azion and
pedro-ribeiro-azion
as code owners
September 22, 2026 22:04
marcus-souza-azion
merged commit Sep 22, 2026
01bd1d1
into
release/new-azion-docs
6 of 8 checks passed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Reworks the Bot Manager section end to end, against the thirteen-slot product structure. The section
was three pages written before the style guide existed, plus eleven guide rows carrying "How to"
titles. The overview ran 505 lines and held a definition, a classification table, a JSON arguments
table, a log-field dictionary and an eight-step challenge procedure under one title; the Bot Manager
Lite reference opened with a second H1 in its body; and two navigation rows pointed at placeholders
no page filled.
The section is now thirteen slots in two languages: overview, quickstart, how it works, three
reference pages, limits, best practices, troubleshooting, glossary, an examples index with four
snippet pages, the guides hub with eight rewritten and three scope-edited rows, and pricing and changelog as links. One slot
stays empty, because Bot Manager's surfaces are one function instance, its output, and the Lite
function — a features page would restate the overview one level down.
A verification run against a real account settled the facts the pages rest on, and corrected several
the corpus had wrong. Bot Manager is not a firewall module: it runs as a function instance on a
firewall, and the v4 specification declares no such module. The rule behavior carries the instance
id in
value— notname, notfunction_id, and not the installed function's id, which is themistake every previous page invited. Bot Manager Lite ships
actionasdenyat a threshold of30, so an instance created with an empty arguments object refuses the first request that crossesit. Network list
2is Azion IP Tor Exit Nodes, not the Origin Shield addresses one guide named. Anargument change reaches the request path in about two minutes, so a re-test run immediately after one
describes the arguments that preceded it.
One mechanism nobody had documented now appears where a reader meets it:
classifiedis computedagainst the threshold in force rather than against the score, so one score of 28 reads
legitimateat a threshold of 30 and
bad botat a threshold of 1. Raising a threshold therefore relabelstraffic in the report log and in every chart built on it, and a week-over-week count is comparable
only across an unchanged threshold.
Three silent failure modes are documented for the first time. The arguments object is not validated
at all: a misspelled key is accepted by every interface, stored, echoed back byte for byte, and
ignored while the function runs on its default, so an argument nobody read and an argument that had
no effect look identical from outside. A Rules Engine criterion matching on query-string arguments
does not match a request that carries no query string, so a rule built that way skips every POST with
its payload in the body. And a request the function has not classified is answered with
204and anempty body, which is neither a refusal nor a pass.
No permalink moved, so no redirect is owed. Every inbound anchor was repointed instead: four pointed
at an overview anchor the rewrite removed, and the rest at headings that no longer exist.
Related issue: none
Pages affected:
/documentation/secure/bot-manager/·/quickstart/·/how-it-works/·/arguments/·/logs/·/bot-manager-lite/·/limits/·/best-practices/·/troubleshooting/·/glossary/·/examples/and its four snippet pages ·/guides/, plus the eleven guides the hub lists and every Portuguese twinCoverage
The same frozen set of 95 reader questions, in the same wording and order, scored against the section
before the rework and again as it shipped. Nothing external was re-read between the two runs.
Nothing regressed, checked by joining the two measurements row by row. One question is excluded
from both denominators as not applicable.
Type of change
feat)fix) — typo, broken link, wrong informationdocs) — rewrite, expansion, upkeepi18n)refactor/chore) — reviewed by UXE, no content mixed inAuthor checklist
type(scope): summary(see GOVERNANCE.md §4)title,description,meta_tags,namespace,permalink,last_reviewedpt-brupdated in this PR or follow-upi18nissue created: every Portuguese twin is written in this PRpnpm build:local(build + frontmatter check) without errors