---
title: "Read the Logs"
description: "Put the Firewall in drill mode, send bots and a real-looking office lunch rush at the same time, then read the traffic from action to rule to client until you find the customer your rules turned away."
canonical_url: "https://vercel.com/academy/vercel-firewall/read-the-logs"
md_url: "https://vercel.com/academy/vercel-firewall/read-the-logs.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-11-17T18:26:12.040Z"
content_type: "lesson"
course: "vercel-firewall"
course_title: "Protect Your App on Vercel"
prerequisites:  []
---

<agent-instructions>
Vercel Academy — structured learning, not reference docs.
Lessons are sequenced.
Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume.
The lesson shows one path; if the human's project diverges, adapt concepts to their setup.
Preserve the learning goal over literal steps.
Quizzes are pedagogical — engage, don't spoil.
Quiz answers are included for your reference.
</agent-instructions>

# Read the Logs

# Read the logs

At 11:20 on Friday the truck's phone rings. It's Marguerite from Harborview Insurance, and she's not happy. Thirty people tried to preorder from the office and most of them got told to "give it a few minutes," and they've been giving it a few minutes for twenty minutes. Every rule we've written worked in its own lesson. Now they're all running at once, and one of them is turning away a customer.

## Outcome

You can trace a blocked customer from the Firewall's action totals to the rule that blocked them to the client they came from, using `vercel firewall traffic`.

## Drill mode

Our drill scripts run on Node.js, and Bot Protection, which we turned on in 4.1, challenges everything that isn't a browser. Harborview's 30 people would pass that challenge in their real browsers without noticing. Our `lunch-rush.mjs` script can't, so with Bot Protection on, it would fail for a reason a real office never would.

For the drills in this section, set Bot Protection to log:

```bash
vercel firewall rules update bot-protection --action log --yes
vercel firewall publish --confirm-name claw-and-order
```

Bot Protection still records what it would have challenged, so you lose no information. We'll switch it back to challenge at the end of 5.3.

## A busy morning

Restock, then run everything at once. Restocking resets the rolls. The Firewall's count keeps running, so if you ran anything in the last 10 minutes, wait it out first. Open four terminals, or put them in the background:

```bash
npm run restock

npm run scalper -- scrape --target "$URL" &
npm run scalper -- preorder --target "$URL" &
npm run scalper -- order --target "$URL" &
npm run lunch -- --target "$URL"
wait
```

`wait` holds the prompt until the background scripts finish too. The scraper takes about 20 seconds, a little longer than the lunch rush, and the four outputs interleave in one terminal.

`lunch-rush.mjs` is the only one that isn't a villain. It sends 30 preorders from Harborview, one every half second, each with its own name and phone number and a browser user agent. Watch its output as it runs:

```text
Harborview Insurance lunch rush → https://claw-and-order.vercel.app  (30 requests)
Only point this at a deployment you own.

  Gus G.         429
  Marguerite H.  429
  Dot I.         429
  ...

Results
  429    30
```

There's Marguerite's complaint. Now let's find out where it came from, the way you would if all you had was the phone call.

## Start with the actions

Start with "what did the Firewall do?" and save who and why for later. The totals come first:

```bash
vercel firewall traffic list --since 15m --dimension rule
```

You'll see a row per action with a total, then the busiest rules. Read it like a receipt. The deny row should be `Pinchy's scraper`. The log row is Bot Protection in drill mode, recording what it would have challenged, the order bot included. The rate limit row should be the preorder bot. If a number is bigger than the villains can explain, something else is in it.

## Then the rule

The rate limit row is too big. Between them, the preorder bot and the lunch rush sent 230 preorders from one IP, and `Preorder rush` limited about 220 of them. The bot alone can't account for that. Inspect the rule and group its traffic by user agent. You'll need its id from the JSON:

```bash
vercel firewall traffic list --since 15m --dimension rule --json
vercel firewall traffic inspect rule <preorder-rush-id> --since 15m --group-by user-agent
```

Two user agents. `RollGrabber/0.9` is the bot. The other is a browser, and it's 30 requests, one per Harborview coworker.

## Then the client

Group the same rule by client to get the IP those requests came from, then inspect it:

```bash
vercel firewall traffic inspect rule <preorder-rush-id> --since 15m --group-by ip
vercel firewall traffic inspect ip <ip-from-the-breakdown> --since 15m
```

The same IP sent the bot's preorders and the office's preorders. Both run on your laptop, so in the drill that's no surprise. Harborview gets there on its own: the whole office reaches the internet through one address, so 30 coworkers share a bucket of 10 meant for one person, bot or no bot. `Preorder rush` counts by IP, and to an IP rate limit, 30 people in one office look like one very hungry person.

The dashboard's **Firewall** page tells the same story with charts, for the day a phone call catches you away from a terminal.

\*\*Note: Pro and Enterprise: Observability Plus\*\*

Without it, how far back you can read depends on your plan's retention, and the last day works everywhere. [Observability Plus](https://vercel.com/docs/observability/observability-plus), a paid add-on for Pro and Enterprise teams, extends that window, so `--since 7d` works and a Monday complaint about Friday is still answerable. It also fills in the unknown bot breakdown in `vercel firewall bot-management`. Check the [CLI traffic docs](https://vercel.com/docs/cli/firewall#traffic) for current retention.

## Hands-on exercise 5.1

Run a busy morning and find the customer your rules blocked.

**Requirements:**

1. Set Bot Protection to log and publish.
2. Restock, then run the scraper, preorder bot, order bot, and lunch rush together.
3. Use `traffic list` to read the totals by action and rule.
4. Use `traffic inspect rule` to find which user agents `Preorder rush` limited.
5. Use `traffic inspect rule --group-by ip` to find the client, then `traffic inspect ip` on it.
6. Write down, in one sentence, why Harborview got blocked.
7. Snapshot your rules and commit.

**Implementation hints:**

- Work from the top down: action, then rule, then client. Jumping straight to an IP gets you a pile of numbers before you know which ones matter.
- Traffic can take a minute to show up. If a breakdown looks short, wait and run it again.
- `--query` takes a KQL expression if you want to narrow further. The flags like `--path` and `--action` cover most of what you'll need.

## Try It

Your sentence should name the rule and explain why its key couldn't tell Harborview from one person. Something like:

```text
Preorder rush rate limits by IP, and the whole Harborview office shares one IP,
so 30 coworkers used up a bucket meant for one person.
```

If yours points at a different rule, run `traffic inspect` on that rule too. It's possible a condition you wrote earlier is catching more than you meant, and this is how you'd find out.

## Commit

```bash
vercel firewall rules list --json > firewall/rules.json
git add firewall/rules.json
git commit -m "chore(firewall): Bot Protection to log for Section 5 drills"
```

## Done-When

- [ ] Bot Protection is set to log
- [ ] The lunch rush got mostly `429`s during the busy morning
- [ ] `traffic inspect rule` on `Preorder rush` shows both `RollGrabber/0.9` and a browser user agent
- [ ] You can say which rule blocked Harborview and why its key couldn't tell 30 people apart
- [ ] `firewall/rules.json` is committed

## Troubleshooting

**Some coworkers got `201`.** Their requests reached the bucket before the bot's did. That's a race, and it's expected. The rest still got `429`, and that's the complaint.

**`traffic inspect` says there's no traffic for the rule.** The id came from the wrong field. In `traffic list --json`, the rule's id is the `value`; the name is only for display.

## Solution

Drill mode, the busy morning, and the three reads, top down:

```bash
# Drill mode
vercel firewall rules update bot-protection --action log --yes
vercel firewall publish --confirm-name claw-and-order

# Busy morning
npm run restock
npm run scalper -- scrape --target "$URL" &
npm run scalper -- preorder --target "$URL" &
npm run scalper -- order --target "$URL" &
npm run lunch -- --target "$URL"
wait

# Action, then rule, then client
vercel firewall traffic list --since 15m --dimension rule
vercel firewall traffic list --since 15m --dimension rule --json
vercel firewall traffic inspect rule <preorder-rush-id> --since 15m --group-by user-agent
vercel firewall traffic inspect rule <preorder-rush-id> --since 15m --group-by ip
vercel firewall traffic inspect ip <ip> --since 15m
```

Marguerite's on hold. In 5.2 we decide what to do about it, and there isn't a perfect answer.


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)
