Skip to content

Commit b3a9173

Browse files
CopilotCopilot
authored
Add performance benchmarks documentation to website (#204)
1 parent 24e79a6 commit b3a9173

3 files changed

Lines changed: 357 additions & 0 deletions

File tree

‎src/website/src/components/Layout.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,9 @@ const Layout = ({ children, pageTitle }) => {
6060
<li>
6161
<Link to="/api">API Reference</Link>
6262
</li>
63+
<li>
64+
<Link to="/benchmarks">Benchmarks</Link>
65+
</li>
6366
<li>
6467
<Link to="/improvements">Recent Improvements</Link>
6568
</li>

‎src/website/src/pages/benchmarks.js‎

Lines changed: 348 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,348 @@
1+
import * as React from "react"
2+
import { Link } from "gatsby"
3+
import Layout from "../components/Layout"
4+
5+
const BenchmarksPage = () => {
6+
return (
7+
<Layout pageTitle="Performance Benchmarks">
8+
<p style={{ fontSize: "1.1rem", marginBottom: "2rem" }}>
9+
Measure and understand the performance characteristics of the filter
10+
rule compilers, including parallel chunking speedups and cross-language
11+
comparisons.
12+
</p>
13+
14+
<section>
15+
<h2>Overview</h2>
16+
<p>
17+
The repository includes comprehensive benchmarking tools to help you
18+
understand performance across different compilers and optimize your
19+
compilation workflows. All compilers (TypeScript, .NET, Python, Rust)
20+
support parallel chunking for improved performance with large filter
21+
lists.
22+
</p>
23+
</section>
24+
25+
<section style={{ marginTop: "2rem" }}>
26+
<h2>Benchmarking Tools</h2>
27+
<div className="features">
28+
<div className="feature">
29+
<h3>🚀 Quick Synthetic Benchmark</h3>
30+
<p>
31+
<strong>File:</strong> <code>benchmarks/quick_benchmark.py</code>
32+
</p>
33+
<p>
34+
Fast simulation showing expected speedups without requiring full
35+
compilation setup. Demonstrates:
36+
</p>
37+
<ul>
38+
<li>How rules are split into chunks</li>
39+
<li>Simulated parallel processing time</li>
40+
<li>Expected speedup ratios</li>
41+
</ul>
42+
</div>
43+
<div className="feature">
44+
<h3>📊 Full Benchmark Suite</h3>
45+
<p>
46+
<strong>Files:</strong> <code>benchmarks/run_benchmarks.py</code>,{" "}
47+
<code>generate_synthetic_data.py</code>
48+
</p>
49+
<p>
50+
Complete benchmarking across all compilers with real compilation.
51+
Compares sequential vs chunked/parallel performance using
52+
synthetic test data.
53+
</p>
54+
</div>
55+
</div>
56+
</section>
57+
58+
<section style={{ marginTop: "2rem" }}>
59+
<h2>Running Benchmarks</h2>
60+
61+
<h3>Quick Synthetic Benchmark</h3>
62+
<p>
63+
Run a quick simulation to see expected speedups on your system:
64+
</p>
65+
<pre style={{ marginTop: "0.5rem" }}>
66+
cd benchmarks
67+
<br />
68+
<br />
69+
# Run comparison suite (recommended)
70+
<br />
71+
python quick_benchmark.py --suite
72+
<br />
73+
<br />
74+
# Run parallel scaling test
75+
<br />
76+
python quick_benchmark.py --scaling
77+
<br />
78+
<br />
79+
# Custom benchmark
80+
<br />
81+
python quick_benchmark.py --rules 500000 --parallel 8
82+
<br />
83+
<br />
84+
# Interactive mode
85+
<br />
86+
python quick_benchmark.py --interactive
87+
</pre>
88+
89+
<h3 style={{ marginTop: "2rem" }}>Full Benchmark with Real Compilation</h3>
90+
<p>
91+
Generate synthetic test data and run actual compilation benchmarks:
92+
</p>
93+
<pre style={{ marginTop: "0.5rem" }}>
94+
cd benchmarks
95+
<br />
96+
<br />
97+
# Generate test data (small, medium, large, xlarge filter lists)
98+
<br />
99+
python generate_synthetic_data.py --all
100+
<br />
101+
<br />
102+
# Run benchmarks across all compilers
103+
<br />
104+
python run_benchmarks.py
105+
<br />
106+
<br />
107+
# Run specific compiler only
108+
<br />
109+
python run_benchmarks.py --compiler python --iterations 5
110+
<br />
111+
<br />
112+
# Run specific size only
113+
<br />
114+
python run_benchmarks.py --size large
115+
</pre>
116+
</section>
117+
118+
<section style={{ marginTop: "2rem" }}>
119+
<h2>Expected Performance</h2>
120+
<p>
121+
Performance varies by hardware, I/O speed, and network latency, but
122+
here are typical results from synthetic benchmarks:
123+
</p>
124+
125+
<div style={{ overflowX: "auto", marginTop: "1rem" }}>
126+
<table style={{ width: "100%", borderCollapse: "collapse" }}>
127+
<thead>
128+
<tr style={{ backgroundColor: "#f5f5f5" }}>
129+
<th style={{ padding: "0.75rem", textAlign: "left", borderBottom: "2px solid #ddd" }}>
130+
Rule Count
131+
</th>
132+
<th style={{ padding: "0.75rem", textAlign: "left", borderBottom: "2px solid #ddd" }}>
133+
Sequential
134+
</th>
135+
<th style={{ padding: "0.75rem", textAlign: "left", borderBottom: "2px solid #ddd" }}>
136+
4 Workers
137+
</th>
138+
<th style={{ padding: "0.75rem", textAlign: "left", borderBottom: "2px solid #ddd" }}>
139+
8 Workers
140+
</th>
141+
<th style={{ padding: "0.75rem", textAlign: "left", borderBottom: "2px solid #ddd" }}>
142+
Speedup (8w)
143+
</th>
144+
</tr>
145+
</thead>
146+
<tbody>
147+
<tr>
148+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>10,000</td>
149+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>~150ms</td>
150+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>~60ms</td>
151+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>~40ms</td>
152+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}><strong>3.75x</strong></td>
153+
</tr>
154+
<tr style={{ backgroundColor: "#fafafa" }}>
155+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>50,000</td>
156+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>~600ms</td>
157+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>~200ms</td>
158+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>~120ms</td>
159+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}><strong>5.0x</strong></td>
160+
</tr>
161+
<tr>
162+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>200,000</td>
163+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>~2.5s</td>
164+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>~800ms</td>
165+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>~400ms</td>
166+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}><strong>6.25x</strong></td>
167+
</tr>
168+
<tr style={{ backgroundColor: "#fafafa" }}>
169+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>500,000</td>
170+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>~6s</td>
171+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>~1.8s</td>
172+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>~900ms</td>
173+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}><strong>6.67x</strong></td>
174+
</tr>
175+
</tbody>
176+
</table>
177+
</div>
178+
</section>
179+
180+
<section style={{ marginTop: "2rem" }}>
181+
<h2>Parallel Scaling</h2>
182+
<p>
183+
Speedup scales with CPU cores but with diminishing returns due to
184+
overhead, merge time, and I/O contention:
185+
</p>
186+
187+
<div style={{ overflowX: "auto", marginTop: "1rem" }}>
188+
<table style={{ width: "100%", borderCollapse: "collapse" }}>
189+
<thead>
190+
<tr style={{ backgroundColor: "#f5f5f5" }}>
191+
<th style={{ padding: "0.75rem", textAlign: "left", borderBottom: "2px solid #ddd" }}>
192+
Workers
193+
</th>
194+
<th style={{ padding: "0.75rem", textAlign: "left", borderBottom: "2px solid #ddd" }}>
195+
Theoretical Max
196+
</th>
197+
<th style={{ padding: "0.75rem", textAlign: "left", borderBottom: "2px solid #ddd" }}>
198+
Typical Efficiency
199+
</th>
200+
</tr>
201+
</thead>
202+
<tbody>
203+
<tr>
204+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>2</td>
205+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>2.0x</td>
206+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>90-100%</td>
207+
</tr>
208+
<tr style={{ backgroundColor: "#fafafa" }}>
209+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>4</td>
210+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>4.0x</td>
211+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>85-95%</td>
212+
</tr>
213+
<tr>
214+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>8</td>
215+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>8.0x</td>
216+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>75-90%</td>
217+
</tr>
218+
<tr style={{ backgroundColor: "#fafafa" }}>
219+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>16</td>
220+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>16.0x</td>
221+
<td style={{ padding: "0.75rem", borderBottom: "1px solid #eee" }}>60-80%</td>
222+
</tr>
223+
</tbody>
224+
</table>
225+
</div>
226+
227+
<p style={{ marginTop: "1rem", fontStyle: "italic", color: "#666" }}>
228+
Efficiency decreases due to process startup overhead, merge/deduplication
229+
time, memory bandwidth limits, and I/O contention.
230+
</p>
231+
</section>
232+
233+
<section style={{ marginTop: "2rem" }}>
234+
<h2>When to Use Chunking</h2>
235+
<p>
236+
Parallel chunking provides the most benefit for large filter lists
237+
with multiple sources:
238+
</p>
239+
240+
<div className="features">
241+
<div className="feature">
242+
<h3>✅ Enable Chunking</h3>
243+
<ul>
244+
<li>6+ filter sources</li>
245+
<li>Large combined filter lists (100K+ rules)</li>
246+
<li>Multi-core systems (4+ cores)</li>
247+
<li>Build/CI pipelines</li>
248+
</ul>
249+
</div>
250+
<div className="feature">
251+
<h3>❌ Disable Chunking</h3>
252+
<ul>
253+
<li>1-5 filter sources</li>
254+
<li>Small filter lists (&lt;50K rules)</li>
255+
<li>Memory-constrained systems</li>
256+
<li>Network-bound scenarios (slow downloads)</li>
257+
</ul>
258+
</div>
259+
</div>
260+
</section>
261+
262+
<section style={{ marginTop: "2rem" }}>
263+
<h2>Example Output</h2>
264+
<p>
265+
Here's what you might see from the quick benchmark suite:
266+
</p>
267+
<pre style={{
268+
backgroundColor: "#1e1e1e",
269+
color: "#d4d4d4",
270+
padding: "1rem",
271+
borderRadius: "4px",
272+
overflowX: "auto"
273+
}}>
274+
{`CHUNKING PERFORMANCE COMPARISON SUITE
275+
======================================================================
276+
CPU cores available: 8
277+
Max parallel workers: 8
278+
279+
Size Sequential Parallel Speedup Efficiency
280+
----------------------------------------------------------------------
281+
10K rules 150 ms 70 ms 2.14x 27%
282+
50K rules 570 ms 130 ms 4.38x 55%
283+
200K rules 2,350 ms 350 ms 6.71x 84%
284+
500K rules 5,400 ms 800 ms 6.75x 84%
285+
----------------------------------------------------------------------
286+
287+
Average speedup: 5.00x
288+
Maximum speedup: 6.75x`}
289+
</pre>
290+
</section>
291+
292+
<section style={{ marginTop: "2rem" }}>
293+
<h2>Learn More</h2>
294+
<div className="features">
295+
<div className="feature">
296+
<h3>
297+
<Link to="/chunking-guide">Chunking Guide</Link>
298+
</h3>
299+
<p>
300+
Complete documentation on parallel chunking including
301+
configuration, API reference, and best practices.
302+
</p>
303+
</div>
304+
<div className="feature">
305+
<h3>
306+
<Link to="/compiler-comparison">Compiler Comparison</Link>
307+
</h3>
308+
<p>
309+
Compare the different compiler implementations and choose the
310+
best one for your needs.
311+
</p>
312+
</div>
313+
<div className="feature">
314+
<h3>
315+
<a href="https://github.com/jaypatrick/ad-blocking/tree/main/benchmarks">
316+
View Benchmark Code
317+
</a>
318+
</h3>
319+
<p>
320+
Explore the benchmark scripts on GitHub to understand the
321+
implementation details.
322+
</p>
323+
</div>
324+
</div>
325+
</section>
326+
327+
<section
328+
style={{
329+
marginTop: "2rem",
330+
padding: "1.5rem",
331+
backgroundColor: "#f0f0f0",
332+
borderRadius: "8px",
333+
}}
334+
>
335+
<h2>💡 Tip</h2>
336+
<p>
337+
Run benchmarks on your actual hardware to get accurate performance
338+
data for your specific use case. Results vary based on CPU cores,
339+
memory, I/O speed, and network latency.
340+
</p>
341+
</section>
342+
</Layout>
343+
)
344+
}
345+
346+
export default BenchmarksPage
347+
348+
export const Head = () => <title>Performance Benchmarks - AdGuard Tools and Utilities</title>

‎src/website/src/pages/index.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,12 @@ const IndexPage = () => {
8888
toolkit.
8989
</p>
9090
</div>
91+
<div className="feature">
92+
<h3>
93+
<Link to="/benchmarks">Performance Benchmarks</Link>
94+
</h3>
95+
<p>Measure and optimize compilation performance with benchmarking tools.</p>
96+
</div>
9197
<div className="feature">
9298
<h3>
9399
<Link to="/improvements">Recent Improvements</Link>

0 commit comments

Comments
 (0)