Call and benchmark YARPC services from the command line.
Clone or download
Permalink
Failed to load latest commit information.
encoding Print available proto methods for unrecognized arg (#241) Oct 10, 2018
internal/thrifttest Upgrade to thriftrw 0.4 and yarpc 0.3 (#126) Nov 1, 2016
limiter Use go.uber.org/atomic (#193) Apr 27, 2017
man Regenerate man page and README for latest flags (#216) Sep 6, 2017
peerprovider peerprovider: Use standard library context instead of x/net (#164) Feb 28, 2017
plugin Add flag parser plugin for injecting custom CLI flags (#222) Oct 16, 2017
protobuf Pass parsed `host:port`s to the reflection dialer (#244) Oct 19, 2018
ratelimit Fix benchmark taking longer than duration for low RPS Jul 19, 2016
scripts Fix the release script, use curl instead of ghr (#236) Jun 14, 2018
sorted Improve coverage of sorted/mapkeys package Mar 11, 2016
statsd Adding Verbose flag with new logger for better debugging (#148) Jun 12, 2017
templateargs Add support for template arguments (#179) Apr 7, 2017
testdata Pass parsed `host:port`s to the reflection dialer (#244) Oct 19, 2018
thrift Fix parsing of strings from values that look like ints/bools (#174) Mar 10, 2017
transport Add gRPC transport.Transport (#225, #229) Nov 1, 2017
unmarshal Allow JSON to be used with non-map requests (#86) Jul 28, 2016
.codecov.yml Use codecov instead of coveralls (#206) Jun 9, 2017
.dockerignore Add a rudimentary Dockerfile (#173) Apr 7, 2017
.gitattributes Add protobuf as supported encoding (#238) Oct 4, 2018
.gitignore Cleanup Travis and Makefiles (#226) Oct 30, 2017
.travis.yml Fix the release script, use curl instead of ghr (#236) Jun 14, 2018
CHANGELOG.md Prepare for v0.14.1 release (#245) Oct 22, 2018
Dockerfile Add a rudimentary Dockerfile (#173) Apr 7, 2017
LICENSE Add LICENSE file Apr 2, 2016
Makefile Fix the release script, use curl instead of ghr (#236) Jun 14, 2018
README.md Regenerate man page and README for latest flags (#216) Sep 6, 2017
bench_method.go Internal rename: Rename hostPort to peer (#159) Feb 28, 2017
bench_method_test.go Support grpc reflection when using proto encoding (#239) Oct 16, 2018
bench_state.go Improve digit handling for errors during benchmark (#202) Jun 1, 2017
bench_state_test.go Improve digit handling for errors during benchmark (#202) Jun 1, 2017
benchmark.go Adding Verbose flag with new logger for better debugging (#148) Jun 12, 2017
benchmark_test.go Adding Verbose flag with new logger for better debugging (#148) Jun 12, 2017
doc.go Adress some late codereview feedback on #238 (#240) Oct 9, 2018
glide.lock Add protobuf as supported encoding (#238) Oct 4, 2018
glide.yaml Add protobuf as supported encoding (#238) Oct 4, 2018
integration_test.go Pass parsed `host:port`s to the reflection dialer (#244) Oct 19, 2018
logger.go Adding Verbose flag with new logger for better debugging (#148) Jun 12, 2017
logger_test.go Adding Verbose flag with new logger for better debugging (#148) Jun 12, 2017
main.go Support grpc reflection when using proto encoding (#239) Oct 16, 2018
main_test.go Support grpc reflection when using proto encoding (#239) Oct 16, 2018
options.go Adress some late codereview feedback on #238 (#240) Oct 9, 2018
options_test.go Fix timeouts in templates being ignored (#210) Aug 29, 2017
output.go Adding map to blacklist caller names, tcurl to start (#195) May 5, 2017
parser.go Add flag parser plugin for injecting custom CLI flags (#222) Oct 16, 2017
raffle.bin Add protobuf as supported encoding (#238) Oct 4, 2018
request.go Pass parsed `host:port`s to the reflection dialer (#244) Oct 19, 2018
request_test.go Pass parsed `host:port`s to the reflection dialer (#244) Oct 19, 2018
server_util_test.go Use go.uber.org/atomic (#193) Apr 27, 2017
statsd_fake_test.go Rename all tbench imports -> yab Mar 17, 2016
template.go Use go.uber.org/atomic (#193) Apr 27, 2017
template_test.go Support yab as a shebang without -y (#215) Sep 6, 2017
test.bin Add protobuf as supported encoding (#238) Oct 4, 2018
transport.go Adress some late codereview feedback on #238 (#240) Oct 9, 2018
transport_test.go Adress some late codereview feedback on #238 (#240) Oct 9, 2018
utils_for_test.go Add Jaeger throttling config (#233) Jun 11, 2018
version.go Prepare for v0.14.1 release (#245) Oct 22, 2018

README.md

yab Build Status Coverage Status

yab (Yet Another Benchmarker) is a tool to benchmark YARPC services. It currently supports making Thrift requests to both HTTP and TChannel services.

yab is currently in beta status.

Installing

If you have go installed, simply run the following to install the latest version:

go get -u -f github.com/yarpc/yab

This will install yab to $GOPATH/bin/yab.

Optionally, you can get precompiled binaries from Releases.

Usage

Usage:
  yab [<service> <method> <body>] [OPTIONS]

yab is a benchmarking tool for TChannel and HTTP applications. It's primarily
intended for Thrift applications but supports other encodings like JSON and
binary (raw). It can be used in a curl-like fashion when benchmarking features
are disabled.

yab includes a full man page (man yab), which is also available online:
http://yarpc.github.io/yab/man.html


Application Options:
  -v                             Enable more detailed logging. Repeats increase
                                 the verbosity, ie. -vvv
      --version                  Displays the application version

Request Options:
  -e, --encoding=                The encoding of the data, options are: Thrift,
                                 JSON, raw. Defaults to Thrift if the method
                                 contains '::' or a Thrift file is specified
  -t, --thrift=                  Path of the .thrift file
      --procedure=               The full Thrift method name (Svc::Method) to
                                 invoke
  -m, --method=                  Alias for procedure
  -r, --request=                 The request body, in JSON or YAML format
  -f, --file=                    Path of a file containing the request body in
                                 JSON or YAML
  -H, --header=                  Individual application header as a key:value
                                 pair per flag
      --headers=                 The headers in JSON or YAML format
      --headers-file=            Path of a file containing the headers in JSON
                                 or YAML
  -B, --baggage=                 Individual context baggage header as a
                                 key:value pair per flag
      --health                   Hit the health endpoint, Meta::health
      --timeout=                 The timeout for each request. E.g., 100ms,
                                 0.5s, 1s. If no unit is specified,
                                 milliseconds are assumed. (default: 1s)
  -y, --yaml-template=           Send a tchannel request specified by a YAML
                                 template
  -A, --arg=                     A list of key-value template arguments,
                                 specified as -A foo:bar -A user:me
      --disable-thrift-envelope  Disables Thrift envelopes (disabled by default
                                 for TChannel)
      --multiplexed-thrift       Enables the Thrift TMultiplexedProtocol used
                                 by services that host multiple Thrift services
                                 on a single endpoint.

Transport Options:
  -s, --service=                 The TChannel/Hyperbahn service name
  -p, --peer=                    The host:port of the service to call
  -P, --peer-list=               Path or URL of a JSON, YAML, or flat file
                                 containing a list of host:ports. -P? for
                                 supported protocols.
      --caller=                  Caller will override the default caller name
                                 (which is yab-$USER).
      --rk=                      The routing key overrides the service name
                                 traffic group for proxies.
      --rd=                      The routing delegate overrides the routing key
                                 traffic group for proxies.
      --sk=                      The shard key is a transport header that clues
                                 where to send a request within a clustered
                                 traffic group.
      --jaeger                   Use the Jaeger tracing client to send Uber
                                 style traces and baggage headers
  -T, --topt=                    Transport options for TChannel, protocol
                                 headers for HTTP

Benchmark Options:
  -n, --max-requests=            The maximum number of requests to make. 0
                                 implies no limit. (default: 0)
  -d, --max-duration=            The maximum amount of time to run the
                                 benchmark for. 0 implies no duration limit.
                                 (default: 0s)
      --cpus=                    The number of OS threads
      --connections=             The number of TCP connections to use
      --warmup=                  The number of requests to make to warmup each
                                 connection (default: 10)
      --concurrency=             The number of concurrent calls per connection
                                 (default: 1)
      --rps=                     Limit on the number of requests per second.
                                 The default (0) is no limit. (default: 0)
      --statsd=                  Optional host:port of a StatsD server to
                                 report metrics

Help Options:
  -h, --help                     Show this help message

Making a single request

The following examples assume that the Thrift service running looks like:

service KeyValue {
  string get(1: string key)
}

If a TChannel service was running with name keyvalue on localhost:12345, you can make a call to the get method by running:

yab -t ~/keyvalue.thrift -p localhost:12345 keyvalue KeyValue::get -r '{"key": "hello"}'

This specifies a single host:port using -p, but you can also specify multiple peers by passing the -p flag multiple times:

yab -t ~/keyvalue.thrift -p localhost:12345 -p localhost:12346 keyvalue KeyValue::get -r '{"key": "hello"}'

If you have a file containing a list of host:ports (either JSON or new line separated), you can specify the file using -P:

yab -t ~/keyvalue.thrift -P ~/hosts.json keyvalue KeyValue::get -r '{"key": "hello"}'

yab also supports HTTP, instead of the peer being a single host:port, you would use a URL:

yab -t ~/keyvalue.thrift -p "http://localhost:8080/rpc" keyvalue KeyValue::get -r '{"key": "hello"}'

Benchmarking

To benchmark an endpoint, you need all the command line arguments to describe the request, followed by benchmarking options. You need to set at least --maxDuration (or -d) to set the maximum amount of time to run the benchmark.

You can set values such as 3s for 3 seconds, or 1m for 1 minute. Valid time units are:

  • ms for milliseconds
  • s for seconds
  • m for minutes.

You can also control rate limit the benchmark (--rps), or customize the number of connections (--connections) or control the amount of concurrent calls per connection (--concurrency).

yab -t ~/keyvalue.thrift -p localhost:12345 keyvalue KeyValue::get -r '{"key": "hello"}' -d 5s --rps 100 --connections 4