README.md
1# apib: API Bench
2
3This is a tool that makes it easy to run performance tests of HTTP API servers. It is built
4using [Bazel](https://www.bazel.build/) and can be built on most Linux platforms, plus Mac OS X and FreeBSD.
5
6## Status
7
8apib has been fairly stable for a little while now. Please submit issues
9or pull requests if you find that you'd like it to do more within reason!
10
11## Current Version
12
131.0.
14
15## Usage
16
17Running apib can be as simple as:
18
19 apib -c 100 -d 60 http://test.example.com
20
21The command above will hammer "test.example.com" as fast as it can for up to
2260 seconds using 100 concurrent network connections.
23
24## Installation
25
26On the Mac, you can now install via [Homebrew](http://brew.sh/):
27
28 brew install apib
29
30Otherwise, you can [build it yourself from source](./doc/BUILDING.md).
31
32See additional documentation for more:
33
34* [Running](./doc/RUNNING.md): How to run apib
35* [Building](./doc/BUILDING.md): How to build it from source
36* [Remote Montitoring](./doc/REMOTE-MONITORING.md): How to remotely monitor servers under test
37
38## Design
39
40apib has most of the features of Apache Bench (ab), but is also intended as
41a more modern replacement. In particular, it supports:
42
43* Proper HTTP 1.1 support including keep-alives and chunked encoding
44* Ability to spawn multiple I/O threads to take advantage of multiple
45 CPU cores
46* Support for POST and PUT of large objects
47* Support for OAuth 1.0 signatures
48* Ability to output results to a file so they may be automated
49* Remote CPU monitoring
50
51In addition, like "ab," it also supports:
52
53* A simple command-line interface
54* Few dependencies, so it may be easily built and deployed
55* Non-blocking I/O for high concurrency
56
57## Implementation:
58
591. Spawn one I/O thread per CPU (configured by user)
602. Allocate a subset of connections to each, and in each:
613. Start event loop
624. If total number of connections < C, spawn a connection
635. Execute HTTP state machine -- connecting, sending, receiving, sending
646. When connections close, replace them to maintain C connections open
657. Record results in a shared area
668. Back in main thread, report on shared results periodically
679. Time in main thread and signal workers to stop eventually
6810. Report to screen and to file
69