If set to "equal_opportunity", all benchmark runs that are configured (see below) under this ApacheBench object are given equal access to the concurrency level. This means requests are taken from each run and sent in parallel (the level of parallelism defined by concurrency()).

If set to "run_priority", the benchmark runs that are configured first get the highest priority. This means all requests in $b->run(0) will be sent before any requests in $b->run(1) are sent, provided that $b->run(0)->order eq "breadth_first" (see below).

See "EXAMPLES" near the bottom of this manual for a tutorial on the effects of "equal_opportunity" vs. "run_priority".

(default: "equal_opportunity")

(default: 1)

Warning: If you configure runs which contain requests to more than one hostname/port, be aware that setting $b->keepalive() may not improve performance. See the discussion in the $run->keepalive() section for more details.

(default: 0)

Per-url/per-run time limits can also be specified using the $run->timelimits() method, but it does not override this global setting. If $b->timelimit() is set, ApacheBench will exit after $sec_to_max_wait (or slightly over, due to final connection reads and building regression data), regardless of any other settings.

(default: 0, which means wait an unlimited amount of time)

(default: 262144 or 256K)

(default: 8192 or 8K)

(default: 1)

Key: $memlvl => Description

  0  =>  Remember nothing. (actually still keeps global
         regression data: total_time, bytes_received,
         and warnings)

  1  =>  Remember connect/response times and minimal
         summary information about size of requests and
         responses.

  2  =>  Remember connect/response times and all
         information about size of requests and responses.
         Also keeps an array of all HTTP response
         headers returned by the server for each request.

  3  =>  Remember connect/response times, all information
         about request/response sizes, HTTP response
         headers, and also all content of every HTTP
         response returned by the server.  B<Warning>:
         this can quickly eat up all available main
         memory if used with large runs.
    

(default: 1, or whatever is specified in global configuration)

(default: 1)

If you need to set different cookies within a single URL sequence, use the request_headers() method.

Note: this is somewhat obsolete now that there is support for dynamic cookies, but is kept for backwards compatibility and in case you want to add your own "static" cookies.

Example usage: You could simulate $n users all doing the same transaction simultaneously by giving $n different login cookies here. Say you have login cookies in an array called @login of length $n. Set $run->repeat($n), $run->order("breadth_first"), $run->cookies([map {$login[$_]} 0..$n-1]), and ApacheBench will perform the transaction sequence set by $run->urls $n times, each with a separate login cookie.

Length of @postdata should equal the length of @url_list.

The @postdata array should consist of either strings or code refs (or undef). A string value will make this request always a POST. An undef makes this request always a GET. If a code ref, it will depend on the return value of the called code. (see below for details)

The strings should contain exactly what you want sent in the HTTP POST request body. For example,

  @postdata = (undef, undef, 'cgikey1=val1&cgikey2=val2');
    

will send two GET requests, then a POST request with the CGI parameter 'cgikey1' set to 'val1' and the CGI parameter 'cgikey2' set to 'val2'.

The code refs should be references to subroutines that take one string argument, which will be the http response (both headers and body) returned from the *previous* request in this run, and return CGI post data as above. If a subroutine returns undef, then the request will be a GET rather than a POST. If the return value is a string (even empty string), the request sent will be a POST with the string as the request body.

For example,

  @postdata = (undef, sub($) {
    my $prev_response = shift;
    my ($username) = ( $prev_response =~ m|<div id="userName">([^<>]+)</div>|i );
    return $username ? 'cgi-username='.$username : undef;
  });
    

will send one GET request, then it will scan the HTTP response body returned by the server for that GET request, and pull out any text (non-HTML) inside the HTML div with id = "userName".

This text is then sent in a POST request as the value of CGI parameter 'cgi-username'. If the <div id="userName"> element is not found in the most recent http response, then the second request will be a GET instead of a POST request.

WARNING: when using code refs in @postdata, you need to be running with $run->memory(3), since it needs to remember the most recent http response content. If you forget, you will be warned at runtime (and your POST requests will likely not send the desired content).

NOTES:

 1. The time taken to call your postdata function is not included in the
    times reported in the Regression object.  This is intentional, so you can
    benchmark your server response time, not your load testing script.

 2. You can use the above property to implement a random delay between http
    requests; while this is sort of a hack of the postdata function feature,
    it is much easier to implement a random delay this way than to add it in C.

    e.g. the following postdata coderef would produce a GET request with a
         random 1-5 sec delay:

    sub($) {
        sleep(int(rand(5)) + 1);
        return undef;
    }
    

You can configure a run composed of any combination of the three HTTP request types (GET, HEAD, and POST), but note that an individual URL with a defined postdata() value will cause a POST request regardless of whether head_requests() is set for that URL. The following precedence table illustrates which type of request will be sent for URL $url_no in the sequence.

  defined $run->postdata->[$url_no] && ! ref($run->postdata->[$url_no])
                                     ?  ==> POST request
  defined $run->postdata->[$url_no] && ref($run->postdata->[$url_no]) eq 'CODE'
           && defined $run->postdata->[$url_no]->( $preceding_response )
                                     ?  ==> POST request
  defined $run->postdata->[$url_no] && ref($run->postdata->[$url_no]) eq 'CODE'
           && ! defined $run->postdata->[$url_no]->( $preceding_response )
                                     ?  ==> GET request
  $run->head_requests->[$url_no]     ?  ==> HEAD request
  else                               :  ==> GET request
    

The following example for a @url_list of length 4 produces two requests with no extra headers, one with 1 extra header, and one with 2 extra headers.

  $run->request_headers([ undef, undef, "Extra-Header: bread",
                          "Extra-Header1: butter\r\nExtra-Header2: toaster" ])
    

To achieve full performance benefits from this feature, you need to be sure your Keep-Alive requests are consecutive. If a non-Keep-Alive request or a request for a different hostname or port immediately follows a Keep-Alive request in the connection slot, the connection will be closed and a new connection will be opened.

Further, keep in mind that for $b->concurrency() > 1, there are many connection slots open and even though requests in @url_list will be sent in order, there is no guarantee they will all use the same connection slot. The HTTP Keep-Alive feature only yields performance benefits when consecutive Keep-Alive requests use the same connection slot. Otherwise ApacheBench has to close and re-open connections, resulting in the same performance as not using keepalive() at all.

To guarantee consecutive Keep-Alive requests with $b->concurrency() > 1, I recommend you either declare all URLs in all runs as keepalive() (this can be done by setting $b->keepalive( 1 ) and not overriding it by calling keepalive() for any runs), or set $run->order( "depth_first" ) and $b->priority( "run_priority" ). This is the only combination of configuration options that guarantees consecutive, same-slot Keep-Alive requests regardless of your concurrency setting.

For $b->concurrency() == 1, things are simpler. At any given time, there is only one connection slot open, so just make sure your keepalive URLs are consecutive within each run (if in "run_priority" mode), or that equal-numbered repetitions of URLs in all runs are keepalive (if in "equal_opportunity" mode), and be sure that all requests are to the same hostname/port.

Warning: once the specified number of seconds have elapsed on the specified URL, ApacheBench will close the connection immediately. This can cause strange results in the regression data for this request. It could also result in partially received responses, which will cause broken sockets for the server.

"breadth_first" mode sends $n of the first request in the @url_list, then $n of the second request in the @urls_list, then $n of the third... and so on. (e.g. If $n == 3 and @url_list contains two requests, then ApacheBench would send the first request 3 times, and then the second request 3 times.)

"depth_first" mode ensures that HTTP requests in the sequence are sent in order, completing a full sequence before starting again for the next repeat() iteration. (e.g. If $n == 3 and @url_list contains two requests, then ApacheBench would send the @url_list sequence in order, then send it again, and then again. A total of six requests would be sent.)

See "EXAMPLES" near the bottom of this manual for a tutorial on the effects of "breadth_first" vs. "depth_first".

(default: "breadth_first")

Note: if $run->repeat() == 1, or the length of $run->urls() is 1, then the order option has no effect

(default: 262144 or 256K, or whatever is specified in global configuration)

(default: 1, or whatever is specified in global configuration)

Note: this method is automatically called from execute() before entering any XS code.

If $url_no is not given, returns a reference to an array the same length as $run->urls() which contains the number of successful HTTP requests sent for each url in this run.

If $url_no is not given, returns a reference to an array the same length as $run->urls() which contains the number of successful HTTP responses received for each HTTP request in this run.

If $url_no is not given, returns a reference to an array the same length as $run->urls() which contains the number of unsuccessful HTTP responses received for each HTTP request in this run.

If $url_no is not given, returns a reference to an array the same length as $run->urls() which contains connection times, in milliseconds, for each HTTP request in this iteration of the sequence.

If $url_no is not given, returns a reference to an array the same length as $run->urls() which contains the times taken to send a request to the server, in milliseconds, for each HTTP request in the sequence.

If $url_no is not given, returns a reference to an array the same length as $run->urls() which contains the times taken to receive a response from the server, in milliseconds, for each HTTP request in the sequence.

If $url_no is not given, returns a reference to an array the same length as $run->urls() which contains the number of bytes posted to the server for each HTTP request in the sequence.

(return value will be undefined if memory < 2)

If $url_no is not given, returns a reference to an array the same length as $run->urls() which contains the total number of bytes read from the server in each HTTP response in the sequence.

(return value will be undefined if memory < 2)

If $url_no is not given, returns a reference to an array the same length as $run->urls() which contains the full HTTP request (including HTTP request headers) sent to the server for each URL in the sequence.

(return value will be undefined if memory < 3)

If $url_no is not given, returns a reference to an array the same length as $run->urls() which contains the HTTP response headers returned by the server for each URL in the sequence.

(return value will be undefined if memory < 2)

If $url_no is not given, returns a reference to an array the same length as $run->urls() which contains the full HTTP responses returned by the server for each URL in the sequence.

(return value will be undefined if memory < 3)

If $url_no is not given, returns a reference to an array the same length as $run->urls() which contains the length of the document (in bytes) returned by the server for each HTTP response in the sequence. This should be equivalent to the Content-Length: line in the response headers, if the server set them correctly. The following should also be true, for 1 <= $j <= size($run->urls()):

( $i->response_body_lengths()->[$j] == $i->bytes_read()->[$j] - length($i->response_headers()->[$j]) )

(return value will be undefined if memory < 2)