Skip to content

Commit b392081

Browse files
author
OpenCode
committed
Add doc for viewing botstopper logs
1 parent 41a90ab commit b392081

2 files changed

Lines changed: 151 additions & 11 deletions

File tree

‎docs/hypernode-platform/botstopper/how-to-use-botstopper.md‎

Lines changed: 1 addition & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -233,17 +233,7 @@ You usually do not need allow rules for API or webhook traffic. Botstopper allow
233233

234234
The botstopper service logs to `/var/log/botstopper/botstopper.log`. The log file consists [JSON Lines](https://jsonlines.org/), meaning that each line in the log file is a JSON-parseable line.
235235

236-
You can render the entire log file:
237-
238-
```bash
239-
cat /var/log/botstopper/botstopper.log | jq .
240-
```
241-
242-
Or follow the log file
243-
244-
```bash
245-
tail -f /var/log/botstopper/botstopper.log | jq .
246-
```
236+
To check the Botstopper logs in a human-readable manner, you can use the `hypernode-parse-botstopper-log` command. Read more about it in [How to View Botstopper Logs on Hypernode](./how-to-view-the-logs.md).
247237

248238
## Safe Policy Changes
249239

‎docs/hypernode-platform/botstopper/how-to-view-the-logs.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
myst:
3+
html_meta:
4+
description: Learn how to view Botstopper logs.
5+
title: How to view Botstopper logs on Hypernode | Hypernode
6+
---
7+
8+
# How to View Botstopper Logs on Hypernode
9+
10+
Once you have enabled the Botstopper and it's up-and-running, it's important to monitor its activity and performance. Botstopper logs provide valuable insights into the traffic patterns, blocked requests, and overall effectiveness of the bot mitigation. Here's how you can view the Botstopper logs on your Hypernode.
11+
12+
Use the `hypernode-parse-botstopper-log` CLI tool to view and analyze Botstopper logs in a readable format.
13+
14+
## Log Location
15+
16+
Botstopper writes its logs to:
17+
18+
```text
19+
/var/log/botstopper/botstopper.log
20+
```
21+
22+
The raw log file uses [JSON Lines](https://jsonlines.org/). Each line is a separate JSON object. This is useful for automation, but it is not the easiest format to inspect manually.
23+
24+
## View Today's Logs
25+
26+
Run the parser with `--today` to inspect today's Botstopper log entries:
27+
28+
```console
29+
app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --today
30+
```
31+
32+
The output shows the timestamp, log level, message, and request metadata:
33+
34+
```console
35+
2026-06-05 01:40:05.717877576Z [INF] new challenge issued > host=example.com method=GET path=/ user_agent="Mozilla/5.0 (compatible; CensysInspect/1.1; +https://about.censys.io/)" client_ip=66.132.172.211 accept_language="" priority="" challenge=019e956f-ffd3-735d-9dce-5fe1aa40d534
36+
2026-06-05 02:07:11.959647899Z [INF] new challenge issued > host=example.com method=GET path=/ user_agent="Mozilla/5.0 (X11; Linux x86_64; rv:142.0) Gecko/20100101 Firefox/142.0" client_ip=134.209.40.161 accept_language=en-US,en;q=0.5 priority="u=0, i" challenge=019e9588-d054-7c99-8684-61bbcb099b2f
37+
2026-06-05 02:38:01.225327165Z [INF] new challenge issued > host=example.com method=GET path=/compete-track-tote.html user_agent="Mozilla/5.0 (Linux; Android 5.0) AppleWebKit/537.36 (KHTML, like Gecko) Mobile Safari/537.36 (compatible; TikTokSpider; ttspider-feedback@tiktok.com)" client_ip=47.128.111.110 accept_language=en-US,en;q=0.5 priority="u=0, i" challenge=019e95a5-0807-759a-80d7-f450d68a1923
38+
```
39+
40+
Common messages include `new challenge issued` for visitors or bots that received a browser challenge.
41+
42+
## Filter Logs
43+
44+
Use `--filter` to narrow the output to entries matching a specific field.
45+
46+
For example, only show entries for one host:
47+
48+
```console
49+
app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --today --filter host=example.com
50+
```
51+
52+
Filters support these operators:
53+
54+
| Operator | Meaning |
55+
| -------- | ------- |
56+
| `=` | Field exactly equals the value. |
57+
| `!=` | Field does not equal the value. |
58+
| `~` | Field matches the regular expression. |
59+
| `!~` | Field does not match the regular expression. |
60+
61+
Filter by exact text with `=`:
62+
63+
```console
64+
app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --today --filter client_ip=134.185.85.99
65+
```
66+
67+
Exclude a specific value with `!=`:
68+
69+
```console
70+
app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --today --filter host!=staging.example.com
71+
```
72+
73+
Filter with a regular expression by using `~`:
74+
75+
```console
76+
app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --today --filter path~'^/wp-'
77+
```
78+
79+
Exclude values that match a regular expression with `!~`:
80+
81+
```console
82+
app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --today --filter user_agent!~'(?i)googlebot'
83+
```
84+
85+
Use `--list-fields` to see the available fields:
86+
87+
```console
88+
app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --list-fields
89+
```
90+
91+
## Select a Date
92+
93+
The parser can read logs for different dates:
94+
95+
```console
96+
app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --today
97+
app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --yesterday
98+
app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --days-ago 3
99+
app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --date 2026-06-05
100+
```
101+
102+
Use `--filename` when you want to parse a specific log file:
103+
104+
```console
105+
app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --filename /var/log/botstopper/botstopper.log
106+
```
107+
108+
## Customize Output
109+
110+
By default, the parser prints a useful set of request fields. Use `--fields` to choose which metadata fields are shown after the message:
111+
112+
```console
113+
app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --today --fields host,path,client_ip,user_agent
114+
```
115+
116+
Use `--format` when you want full control over the output format:
117+
118+
```console
119+
app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --today --format '%(time)s [%(level)s] %(msg)s > client_ip=%(client_ip)s host=%(host)s method=%(method)s path=%(path)s'
120+
```
121+
122+
Add `--all` if you also want to include non-request service, startup, and configuration events:
123+
124+
```console
125+
app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --today --all
126+
```
127+
128+
## Command Help
129+
130+
Use `--help` to view all parser options:
131+
132+
```console
133+
app@example-magweb-cmbl ~ $ hypernode-parse-botstopper-log --help
134+
usage: Parse, filter, and inspect botstopper log files. [-h] [--fields FIELDS] [--format FORMAT] [--list-fields] [--filter FILTER] [--verbose] [--all]
135+
[--filename FILENAME | --today | --yesterday | --days-ago DAYS_AGO | --date DATE]
136+
137+
options:
138+
-h, --help show this help message and exit
139+
--fields FIELDS Comma separated list of metadata fields to display after the message. Try: --fields ip,host,req,rule,bot,ua. Use --list-fields to display all available fields.
140+
--format FORMAT Format string to display fields. Example: --format '%(time)s [%(level)s] %(msg)s > client_ip=%(client_ip)s host=%(host)s method=%(method)s path=%(path)s'
141+
--list-fields Display a list of available fields
142+
--filter FILTER Filter to apply. Format: <field>=<str>, <field>!=<str>, <field>~<regex>, or <field>!~<regex>
143+
--verbose, -v Display debug output
144+
--all Include non-request service, startup and config events
145+
--filename FILENAME Path of botstopper logfile to parse
146+
--today Analyze today's log lines
147+
--yesterday Analyze yesterday's log lines
148+
--days-ago DAYS_AGO Analyze logs from a number of days ago
149+
--date DATE Analyze logs from a specific date
150+
```

0 commit comments

Comments
 (0)