DOCSEARCHbyAlgolia
Submit Docs

oha

repository·master·Indexed 27 days ago

https://github.com/hatoo/oha

A lightweight HTTP load generator written in Rust, inspired by rakyll/hey. It features a real-time TUI for monitoring request statistics and supports HTTP/1, HTTP/2, and experimental HTTP/3. oha allows users to configure concurrent connections, request rates (QPS), burst delays, and custom headers, with output options including text, JSON, and CSV.

Tokens
6.6K
Snippets
14
Records
38
Agent score
94%

What's inside oha

  1. Install oha

    master

    You can install oha using several methods depending on your operating system and preferred package manager.

    Via Cargo (Rust)

    Requires make and cmake prerequisites.

    cargo install oha

    Optional Features:

    • Use native-tls instead of rustls: cargo install --no-default-features --features native-tls oha
    • Enable vsock support: cargo install --features vsock oha
    • Enable experimental http3 support (requires rustls): cargo install --features http3 oha

    Package Managers

    • Arch Linux: pacman -S oha
    • macOS (Homebrew): brew install oha
    • Windows (winget): winget install hatoo.oha
    • Debian: Add Azlux's repository and use apt install oha.
    • X-CMD (Linux, macOS, Windows WSL/GitBash): x env use oha

    Containerized

    • Official Docker Image: ghcr.io/hatoo/oha
    • Local Build: docker build -t hatoo/oha:latest .
    • Run via Docker: docker run --rm -it --network=host hatoo/oha:latest <URL>
    cargo install oha

  2. Use oha to generate HTTP load

    master

    The oha CLI is used to send load to a web application and view real-time TUI statistics. The basic syntax is oha [OPTIONS] <URL>. The <URL> can be a single target URL or a file containing multiple URLs.

    Basic Usage

    oha https://example.com

    Realistic Stress Testing

    To simulate more realistic user conditions, it is recommended to use --latency-correction and --disable-keepalive:

    oha -z 30s -c 50 -q 100 --latency-correction --disable-keepalive https://example.com

  3. Configure oha burst requests

    master

    The burst feature allows you to introduce delays between predefined numbers of requests. Note that if -q (QPS) is specified, burst settings are ignored.

    • --burst-delay <BURST_DURATION>: Delay between bursts.
    • --burst-rate <BURST_REQUESTS>: Number of requests per burst. Default: 1.

    Example: To process 4 requests every 2 seconds:

    oha -n 10 --burst-delay 2s --burst-rate 4
    oha -n 10 --burst-delay 2s --burst-rate 4

  4. Configure oha advanced URL and Proxy settings

    master

    Advanced targeting and proxying options:

    • --urls-from-file: Read target URLs from a file.
    • --rand-regex-url: Generate URLs using regex syntax (e.g., http://127.0.0.1/[a-z][a-z][0-9]).
    • --max-repeat <MAX_REPEAT>: Max repeat counts for regex operators. Default: 4.
    • --proxy <PROXY>: HTTP proxy URL.
    • --proxy-header <PROXY_HEADERS>: Custom Proxy HTTP header.
    • --proxy-http-version <PROXY_HTTP_VERSION>: Proxy HTTP version (0.9, 1.0, 1.1, 2).
    • --proxy-http2: Shorthand for --proxy-http-version=2.
    • --connect-to <CONNECT_TO>: Override DNS resolution and port (e.g., example.org:443:localhost:8443).

  5. Configure oha request parameters

    master

    Use the following options to control the load generation behavior:

    • -n <N_REQUESTS>: Total number of requests (e.g., 10k, 1m). Default: 200.
    • -c <N_CONNECTIONS>: Number of concurrent connections. Default: 50.
    • -p <N_HTTP2_PARALLEL>: Parallel requests on HTTP/2. Total workers = c * p. Default: 1.
    • -z <DURATION>: Duration of the test (e.g., 10s, 3m).
    • -w, --wait-ongoing-requests-after-deadline: Wait for ongoing requests to finish after the duration expires (ignored on HTTP/2).
    • -q <QUERY_PER_SECOND>: Rate limit in QPS. Note: -q sets the overall rate, not per worker.
    • -m, --method <METHOD>: HTTP method. Default: GET.
    • -H <HEADERS>: Custom HTTP header (e.g., -H "foo: bar").
    • -d <BODY_STRING>: HTTP request body.
    • -t <TIMEOUT>: Timeout for each request. Default: infinite.
    • --connect-timeout <CONNECT_TIMEOUT>: Timeout for establishing a connection. Default: 5s.

  6. Configure oha HTTP/2 and HTTP/3 settings

    master

    Control the protocol version and connection behavior:

    • --http-version <HTTP_VERSION>: Available values: 0.9, 1.0, 1.1, 2, 3.
    • --http2: Shorthand for --http-version=2.
    • --disable-keepalive: Prevents re-use of TCP connections (not supported for HTTP/2).
    • --disable-compression: Disable compression.
    • --insecure: Accept invalid TLS certificates.

  7. Configure oha output formats

    master

    Specify how the results are presented:

    • --output-format <OUTPUT_FORMAT>:
      • text (default): A text summary.
      • json: A JSON summary (schema defined in schema.json).
      • csv: Each request result is printed as a line of comma-separated values.
      • quiet: Minimal output.
    • -o, --output <OUTPUT>: File to write results to. If omitted, results go to stdout.
    • --no-tui: Disables the real-time TUI animation. This improves performance when -q and --burst-delay are not set.

  9. Use rand_regex for dynamic URL generation

    master

    You can use the --rand-regex-url flag to generate dynamic URLs based on a regex pattern. This is useful for testing how a system handles a large variety of unique paths.

    Note: The . character is automatically disabled in the regex for convenience to ensure valid domain structures. Use --max-repeat to control the expansion of quantifiers like x* or x+.

  10. Generate random URLs using regex

    master

    Use the --rand-regex-url option to generate a unique random URL for each connection based on a provided regular expression. This is useful for simulating varied traffic patterns.

    Note: The regex dot (.) is disabled to prevent it from being interpreted as a regex wildcard, which would interfere with URL structure.

    To limit the number of characters generated by a regex quantifier (e.g., [a-z]*), use the --max-repeat option. For example, --max-repeat 4 will treat [a-z]* as [a-z]{0,4}.

  11. Load test using URLs from a file

    master

    Use the --urls-from-file option to read a list of target URLs from a text file. Each line in the file must contain exactly one valid URL.

    When using this feature, oha will pick a random URL from the file for every request made. This is effective for simulating realistic load distributions (e.g., using URLs extracted from access logs).

  12. Configure Request Generation with RequestGenerator

    master

    The RequestGenerator struct is used to construct HTTP requests for load testing. It manages URL generation, HTTP methods, headers, body types, and optional AWS SigV4 signing or proxy configurations.

    Key configuration fields:

    • url_generator: An instance of url_generator::UrlGenerator used to produce target URLs.
    • https: Boolean indicating if the request should use HTTPS.
    • method: The HTTP Method (e.g., GET, POST).
    • version: The HTTP Version (e.g., Version::HTTP_11, Version::HTTP_2).
    • headers: A HeaderMap containing request headers.
    • body_generator: Determines the request body using BodyGenerator::Static(Bytes) for a fixed body or BodyGenerator::Random(Vec<Bytes>) to pick from a set of bodies.
    • aws_config: An optional AwsSignatureConfig used to apply AWS SigV4 signatures to the request.
    • http_proxy: An optional Proxy struct used when making requests through an HTTP proxy.