From c419c082da0a13ac0ed285853fe316f58f42baa0 Mon Sep 17 00:00:00 2001 From: Matt Jaffee Date: Mon, 6 Mar 2017 11:18:16 -0600 Subject: [PATCH] update readme to reflect subcommands and pilosactl gone --- README.md | 92 +++++-------------------------------------------------- 1 file changed, 8 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index bd6aacbe2..148a7a139 100644 --- a/README.md +++ b/README.md @@ -23,18 +23,16 @@ $ go install github.com/pilosa/pilosa/cmd/... Now run a single pilosa node with the default configuration: ```sh -pilosa +pilosa server ``` -If you would like to quickly create a multi-node pilosa cluster, see the `pilosactl create` documentation. - ## Configuration You can specify a configuration by setting the `-config` flag when running `pilosa`. ```sh -pilosa -config custom-config-file.cfg +pilosa server --config custom-config-file.cfg ``` The config file uses the [TOML](https://github.com/toml-lang/toml) configuration file format, @@ -54,6 +52,12 @@ host = "127.0.0.1:15000" host = "127.0.0.1:15001" ``` +You can generate a template config file with default values with: + +```sh +pilosa config +``` + The first two configuration options will be unique to each node in the cluster: `data-dir`: directory in which data is stored to disk @@ -242,83 +246,3 @@ $ go install --ldflags="-X main.Version=1.0.0" ``` [Glide]: http://glide.sh/ - -## Pilosactl - -Pilosactl contains a suite of tools for interacting with pilosa. Run `pilosactl` for an overview of commands, and `pilosactl -h` for specific information on that command. - -### Create - -`pilosactl create` is used to create pilosa clusters. It has a number of options for controlling how the cluster is configured, what hosts it is on, and even the ability to build the pilosa binary locally and copy it to each cluster node automatically. To start pilosa on remote hosts, you only need `ssh` access to those hosts. See `pilosactl create -h` for a full list of options. - -Examples: - -Create a 5 node cluster locally (using 5 different ports), with a replication factor of 2. -``` -pilosactl create \ - -serverN 5 \ - -replicaN 2 -``` - -Create a cluster on 3 remote hosts - all logs will come to local stderr, pilosa binary must be available on remote hosts. The ssh user on the remote hosts needs to be the same as your local user. Otherwise use the `ssh-user` option. -``` -pilosactl create \ - -hosts="node1.example.com:15000,node2.example.com:15000,node3.example.com:15000" -``` - -Create a cluster on 3 remote hosts running OSX, but build the binary locally and copy it up. Stream the stderr of each node to a separate local log file. -``` -pilosactl create \ - -hosts="mac1.example.com:15000,mac2.example.com:15000,mac3.example.com:15000" \ - -copy-binary \ - -goos=darwin \ - -goarch=amd64 \ - -log-file-prefix=clusterlogs -``` - -### Bagent - -`pilosactl bagent` is what you want if you just want to run a simple benchmark against an existing cluster. Running it with no arguments will print some help, including the set of subcommands that it may be passed. Calling a subcommand with `-h'` will print the options for that subcommand. The `agent-num` flag can be passed an integer which can change the behavior the benchmarks that are run. This is useful when multiple invocations of the same benchmark are made by the `bspawn` command - they can each (for example) set different bits even though they all have the same arguments. - -E.G. -``` -pilosactl bagent \ - -hosts="localhost:15000,localhost:15001" \ - import -h -``` - -Multiple subcommands and their arguments may be concatenated at the command line and they will be run serially. This is useful (i.e.) for importing a bunch of data, and then executing queries against it. - -This will generate and import a bunch of data, and then execute random queries against it. - -``` -pilosactl bagent \ - -hosts="localhost:15000,localhost:15001" \ - import -max-bits-per-map=10000 \ - random-query -iterations 100 -``` - -### Bspawn -`pilosactl bspawn` allows you to automate the creation of clusters and the running of complex benchmarks which span multiple benchmark agents against them. It has a number of options which are described by `pilosactl bspawn` with no arguments, and also takes a config file which describes the Benchmark itself - this file is described below. - -#### Configuration Format - -The configuration file is a json object with the top level key `benchmarks`. This contains a list of objects each of which represents a `bagent` command (the `args` key) that will be run some number of times concurrently (the `num` key), and a `name` which should describe the overall effect that command. An example is below. -```json -{ - "benchmarks": [ - { - "num": 3, - "name": "set-diags", - "args": ["diagonal-set-bits", "-iterations", "30000", "-client-type", "round_robin"] - }, - { - "num": 2, - "name": "rand-plus-zipf", - "args": ["random-set-bits", "-iterations", "20000", "zipf", "-iterations", "100"] - } - ] -} -``` - -All of the benchmarks, and agents are run concurrently. Each agent will be passed an `agent-num` which can modify the behavior in a way that is benchmark specific. See the documentation for each benchmark to see how `agent-num` changes its behavior.