Update README.md

README.md

@@ -1,35 +1,84 @@
 # esperf
 
-Multiplatform command line tool to load test and collect metrics from your [ElasticSearch](https://github.com/elastic/elasticsearch) deployment. Built with love by danielfireman and friends in Go. Esperf provides:
+Is a single-binary multiplatform command line tool to load test and collect metrics from your [ElasticSearch](https://github.com/elastic/elasticsearch) deployment. No need install dependencies or anything. Just download and use. Built with love by danielfireman and friends in Go. Esperf provides:
 
-* Ability to query terms from a dictionary of words
+* Ability to perform queries based on a dictionary of words
 * Ability to properly handle 503 or 429 http responde codes, respecting the delay suggested by the Retry-After response header field.
-* Send load following a constant or Poisson distribution
+* Send query-based load following a constant or Poisson distribution
+* Send query-based load replaying slowlog
 * Collect the following metrics:
      * Overall CPU load
-     * GC time and count (broken by old and young collectors)
+     * GC time and count (broken by full and young collections)
      * Latency 50, 90, 99, 99.9 percentiles
-     * Memory pools usage (broken  by young, survivor and old)
-     * Throughput
+     * Memory pools usage (broken  by young, survivor and tenured)
+     * Throughput and error counters
 
 **Disclaimer: a lot in flux.** 
 
-## Simple Usage
-
-```sh
-$ go get github.com/danielfireman/esperf
-$ echo "word" > tiny_dict.txt
-$ mkdir results
-$ ./esperf --addr http://{ES_SERVER_IP}:9200 \
---load poisson:50 \
---duration 1m \
---results_path=$PWD/results \
---dict=$PWD/tiny_dict.txt
+# Install
+
+## Pre-compiled binaries
+
+Pre-compiled binaries for many platforms can be found [here](https://github.com/danielfireman/esperf/releases).
+
+## Source
+
+You need go installed and `GOBIN` in your `PATH`. Once that is done, run the command:
+
+```bash
+$ go get -u github.com/danielfireman/esperf
+```
+
+## Usage examples
+
+### Custom load specification
+
+Generate a load specification (`poisson.loadspec.json`) that describe the following load test:
+
+* The load test duration is 10s;
+* Trigger term queries using randomly selected strings from `small_dict.txt` dictionary file;
+* Request arrival times will be sent according to the Poisson distribution (lambda parameter equals 5).
+
+```bash
+
+$ echo '{"query": {"term": {"text": {"value": "$RDICT"}}}}' |  ./esperf loadspec gen --arrival_spec=poisson:5 --dictionary_file=small_dict.txt --duration=10s "http://localhost:9200/wikipediax?search_type=query_then_fetch" > poisson.loadspec.json
+```
+
+Using the a loadpspec file to run a loadtest. All the results will be placed at the current directory and statistics will be collected each second from http://localhost:9200.
+
+```bash
+cat poisson.loadspec.json | ./esperf replay --mon_addr=http://localhost:9200 --mon_interval=1s --results_path=$PWD
+```
+
+### Slowlogs-based loadtest
+
+Generate a load specification (`slowlogs.loadspec.json`) based on the passed-in slowlogs. Host, index and other query parameters are going to be extracted from slowlogs. The load test specification will preserve the arrival times or queries, trying to mimick the arrival distribution as much as possible.
+
+```bash
+cat my_slowlogs.log |  ./esperf loadspec parseslowlog > slowlogs.loadspec.json
+```
+
+If you would like to change URL parameters of the query (for instance, replay the loadtests on another host:port).
+
+```bash
+cat my_slowlogs.log |  ./esperf loadspec parseslowlog "http://localhost:9200/wikipediax?search_type=query_then_fetch" > slowlogs.loadspec.json
 ```
 
 ## Why esperf exists?
 
 When researching for tools to load test ES I was quickly reminded by ES REST beauties and pointed out to [JMeter ](http://jmeter.apache.org/) or tools alike. As I needed to conduct experiments with very specific needs, I found that would be easier to build a tool myself than work around.
 
+Also, I couldn't find a spec format that would respect the distribution of the arrival times. In particular, when parsing slowlogs, I would like to replay that respecting as much as possible the arrival times that were collected. I took a look at [Vegeta](https://github.com/tsenart/vegeta/) and [Yandex-Tank](https://github.com/yandex/yandex-tank) formats. 
+
 On the metrics side, I took a look at some ES plugins (i.e. [Marvel](https://www.elastic.co/downloads/marvel)) but I also bumped into some restrictions, for instance tune the metrics collection interval, pic and choose metrics and have access to raw data (CSV) to play with them in platforms like [R](https://www.r-project.org/) :heart:
 
+# Inspiration
+
+* [kosho/esperf](https://github.com/kosho/esperf): loadspec gen inspiration.
+* [coxx/es-slowlog](https://github.com/coxx/es-slowlog): ideas and pointers to other loadspec file formats
+
+# Thanks
+
+* [Péter Szilágyi](https://github.com/karalabe) for [Xgo](https://github.com/karalabe/xgo), which turned cross-compiling go programs into a breeze
+* [Steve Francia](https://github.com/spf13) and others for [Cobra](https://github.com/spf13/cobra), great framework for building command-line tools in go
+