Skip to main content

Running the engine

1. Prepare a test guild​

Create a Discord guild and put bucketmap in its name: the engine refuses to touch any guild without this marker. Invite your bot as an administrator, and four accounts to act as test users.

2. Install​

go install github.com/FCAgreatgoals/bucketmap/cmd/bucketmap@latest

3. Run​

export TOKEN=your-bot-token
bucketmap run -guild GUILD_ID -users USER1,USER2,USER3,USER4

The run takes ten minutes, prints a summary, and writes the full report to bucketmap.json. Everything it creates is deleted at the end.

What a run gives you​

  • Every request, and its answer: status, latency, and the rate limit headers Discord sent.
  • Every bucket met: its limit, how long it takes to refill, and whether it refills one request at a time or all at once. Buckets shared by several routes are flagged.
  • Every failure: a step that did not answer as expected, and every 429, which should never happen, since the engine never pushes a bucket to its end.

The numbers are your bot's own: Discord's limits differ from one application to another, and change over time.

bucketmap run options​

  • -guild: ID of the test guild;
  • -users: IDs of the four test users, comma separated;
  • -token: bot token, without the Bot prefix (defaults to the TOKEN variable);
  • -api: API root to test, Discord by default (https://discord.com/api/v10), or your proxy;
  • -report: report file (bucketmap.json by default);
  • -duration: how long to spread the run over (10m by default);
  • -marker: text the guild name must contain (bucketmap by default).

What the engine touches​

The engine only works in the guild whose name carries the marker. It spreads about 270 requests over the run, waits out any bucket that reports nothing left, and never retries a 429. Every request carries an audit log reason naming its step, and everything it creates is named bucketmap and deleted at the end.

What cannot be undone within a run only happens when you ask for it:

  • -allow-kick: kicks test user 3;
  • -allow-ban: bans then unbans test user 4, one by one and in bulk;
  • -allow-prune: prunes members inactive for thirty days who hold no role;
  • -allow-global-commands: creates then deletes a global command, seen for a moment in every guild of the bot.

Kicked and banned users rejoin through the invite printed at the end. Steps that need a community guild (announcement and stage channels, welcome screen, membership screening) run when the guild has the COMMUNITY feature.

Coverage​

bucketmap coverage

Shows the routes the engine exercises: 179 on every run, and 24 more under a flag or on a community guild. The rest need an interaction started by a user, an OAuth2 token, or would change something a run cannot restore: each one says why in its notes.

bucketmap version prints the installed version.