Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: nats-io/natscli
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: 0.0.25
Choose a base ref
...
head repository: nats-io/natscli
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: 0.0.26
Choose a head ref
2 contributors
Loading
183 changes: 125 additions & 58 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
## The NATS Command Line Interface
## The NATS Command Line Interface

A command line utility to interact with and manage NATS.

@@ -7,14 +7,14 @@ and support full JetStream management.

### Features

* JetStream management
* JetStream data and configuration backup
* Message publish and subscribe
* Service requests and creation
* Benchmarking and Latency testing
* Super Cluster observation
* Configuration context maintenance
* NATS eco system schema registry
* JetStream management
* JetStream data and configuration backup
* Message publish and subscribe
* Service requests and creation
* Benchmarking and Latency testing
* Super Cluster observation
* Configuration context maintenance
* NATS eco system schema registry

### Installation

@@ -82,7 +82,7 @@ The `nats` CLI can publish messages and subscribe to subjects.
#### Basic Behaviours

We will subscribe to the `cli.demo` subject:

```
$ nats sub cli.demo
12:30:25 Subscribing on cli.demo
@@ -215,58 +215,125 @@ default messages are published as quick as possible without any acknowledgement

```
$ nats bench test --msgs=10000000 --pub 5 <13:03:30
13:03:34 Starting benchmark [msgs=10,000,000, msgsize=128 B, pubs=5, subs=0]
0s [====================================================================] 100%
0s [====================================================================] 100%
0s [====================================================================] 100%
0s [====================================================================] 100%
0s [====================================================================] 100%
Pub stats: 12,930,556 msgs/sec ~ 1.54 GB/sec
[1] 2,997,680 msgs/sec ~ 365.93 MB/sec (2000000 msgs)
[2] 2,969,136 msgs/sec ~ 362.44 MB/sec (2000000 msgs)
[3] 2,965,889 msgs/sec ~ 362.05 MB/sec (2000000 msgs)
[4] 2,612,872 msgs/sec ~ 318.95 MB/sec (2000000 msgs)
[5] 2,592,706 msgs/sec ~ 316.49 MB/sec (2000000 msgs)
min 2,592,706 | avg 2,827,656 | max 2,997,680 | stddev 184,047 msgs
01:30:14 Starting benchmark [msgs=10,000,000, msgsize=128 B, pubs=5, subs=0, js=false, stream=benchstream storage=memory, syncpub=false, pubbatch=100, jstimeout=30s, pull=false, pullbatch=100, request=false, reply=false, noqueue=false, maxackpending=-1, replicas=1, purge=false]
Finished 0s [================================================] 100%
Finished 0s [================================================] 100%
Finished 0s [================================================] 100%
Finished 0s [================================================] 100%
Finished 0s [================================================] 100%
Pub stats: 14,047,987 msgs/sec ~ 1.67 GB/sec
[1] 3,300,540 msgs/sec ~ 402.90 MB/sec (2000000 msgs)
[2] 3,306,601 msgs/sec ~ 403.64 MB/sec (2000000 msgs)
[3] 3,296,538 msgs/sec ~ 402.41 MB/sec (2000000 msgs)
[4] 2,813,752 msgs/sec ~ 343.48 MB/sec (2000000 msgs)
[5] 2,811,227 msgs/sec ~ 343.17 MB/sec (2000000 msgs)
min 2,811,227 | avg 3,105,731 | max 3,306,601 | stddev 239,453 msgs
```

Adding `--sub 2` will start two subscribers on the same subject and measure the rate of messages:

```
$ nats bench test --msgs=10000000 --pub 5 --sub 2
...
Sub stats: 3,046,055 msgs/sec ~ 371.83 MB/sec
[1] 1,523,030 msgs/sec ~ 185.92 MB/sec (10000000 msgs)
[2] 1,523,030 msgs/sec ~ 185.92 MB/sec (10000000 msgs)
min 1,523,030 | avg 1,523,030 | max 1,523,030 | stddev 0 msgs
```

JetStream testing can be done by adding the `--ack` flag which will publish messages and wait for acknowledgements
from JetStream that a message was successfully saved. Without the `--ack` publishing to a JetStream subject would
just send the messages as fast as possible.

```
$ nats bench js.in.bench --msgs=100000 --pub 5 --ack <13:06:00
13:07:52 Starting benchmark [msgs=100,000, msgsize=128 B, pubs=5, subs=0]
13:07:52 Disabling progress bars in request mode
13:07:52 Starting publisher, publishing 20,000 messages
13:07:52 Starting publisher, publishing 20,000 messages
13:07:52 Starting publisher, publishing 20,000 messages
13:07:52 Starting publisher, publishing 20,000 messages
13:07:52 Starting publisher, publishing 20,000 messages
Pub stats: 55,290 msgs/sec ~ 6.75 MB/sec
[1] 11,092 msgs/sec ~ 1.35 MB/sec (20000 msgs)
[2] 11,086 msgs/sec ~ 1.35 MB/sec (20000 msgs)
[3] 11,073 msgs/sec ~ 1.35 MB/sec (20000 msgs)
[4] 11,066 msgs/sec ~ 1.35 MB/sec (20000 msgs)
[5] 11,067 msgs/sec ~ 1.35 MB/sec (20000 msgs)
min 11,066 | avg 11,076 | max 11,092 | stddev 10 msgs
```

There are numerous other flags that can be set to configure size of messages, number of workers and more, see `nats bench --help`.
01:30:52 Starting benchmark [msgs=10,000,000, msgsize=128 B, pubs=5, subs=2, js=false, stream=benchstream storage=memory, syncpub=false, pubbatch=100, jstimeout=30s, pull=false, pullbatch=100, request=false, reply=false, noqueue=false, maxackpending=-1, replicas=1, purge=false]
01:30:52 Starting subscriber, expecting 10,000,000 messages
01:30:52 Starting subscriber, expecting 10,000,000 messages
Finished 6s [================================================] 100%
Finished 6s [================================================] 100%
Finished 6s [================================================] 100%
Finished 6s [================================================] 100%
Finished 6s [================================================] 100%
Finished 6s [================================================] 100%
Finished 6s [================================================] 100%
NATS Pub/Sub stats: 4,906,104 msgs/sec ~ 598.89 MB/sec
Pub stats: 1,635,428 msgs/sec ~ 199.64 MB/sec
[1] 328,573 msgs/sec ~ 40.11 MB/sec (2000000 msgs)
[2] 328,147 msgs/sec ~ 40.06 MB/sec (2000000 msgs)
[3] 327,411 msgs/sec ~ 39.97 MB/sec (2000000 msgs)
[4] 327,318 msgs/sec ~ 39.96 MB/sec (2000000 msgs)
[5] 327,283 msgs/sec ~ 39.95 MB/sec (2000000 msgs)
min 327,283 | avg 327,746 | max 328,573 | stddev 520 msgs
Sub stats: 3,271,233 msgs/sec ~ 399.32 MB/sec
[1] 1,635,682 msgs/sec ~ 199.67 MB/sec (10000000 msgs)
[2] 1,635,616 msgs/sec ~ 199.66 MB/sec (10000000 msgs)
min 1,635,616 | avg 1,635,649 | max 1,635,682 | stddev 33 msgs
```

JetStream testing can be done by adding the `--js` flag. You can for example measure first the speed of publishing into a stream

```
$ nats bench js.bench --js --pub 2 --msgs 1000000 --purge
01:37:36 Starting benchmark [msgs=1,000,000, msgsize=128 B, pubs=2, subs=0, js=true, stream=benchstream storage=memory, syncpub=false, pubbatch=100, jstimeout=30s, pull=false, pullbatch=100, request=false, reply=false, noqueue=false, maxackpending=-1, replicas=1, purge=true]
01:37:36 Purging the stream
Finished 2s [================================================] 100%
Finished 2s [================================================] 100%
Pub stats: 415,097 msgs/sec ~ 50.67 MB/sec
[1] 207,907 msgs/sec ~ 25.38 MB/sec (500000 msgs)
[2] 207,572 msgs/sec ~ 25.34 MB/sec (500000 msgs)
min 207,572 | avg 207,739 | max 207,907 | stddev 167 msgs
```
And then you can for example measure the speed of receiving (i.e. replay) the messages from the stream using ordered push consumers
```
$ nats bench js.bench --js --sub 4 --msgs 1000000
01:40:05 Starting benchmark [msgs=1,000,000, msgsize=128 B, pubs=0, subs=4, js=true, stream=benchstream storage=memory, syncpub=false, pubbatch=100, jstimeout=30s, pull=false, pullbatch=100, request=false, reply=false, noqueue=false, maxackpending=-1, replicas=1, purge=false]
01:40:05 Starting subscriber, expecting 1,000,000 messages
01:40:05 Starting subscriber, expecting 1,000,000 messages
01:40:05 Starting subscriber, expecting 1,000,000 messages
01:40:05 Starting subscriber, expecting 1,000,000 messages
Finished 2s [================================================] 100%
Finished 2s [================================================] 100%
Finished 2s [================================================] 100%
Finished 2s [================================================] 100%
Sub stats: 1,522,920 msgs/sec ~ 185.90 MB/sec
[1] 382,739 msgs/sec ~ 46.72 MB/sec (1000000 msgs)
[2] 382,772 msgs/sec ~ 46.73 MB/sec (1000000 msgs)
[3] 382,407 msgs/sec ~ 46.68 MB/sec (1000000 msgs)
[4] 381,060 msgs/sec ~ 46.52 MB/sec (1000000 msgs)
min 381,060 | avg 382,244 | max 382,772 | stddev 698 msgs
```

Similarily you can benchmark synchronous request/reply type of interactions using the `--request` and `--reply` flags. For example you can first start one (or more) replier(s)

```
$ nats bench test --sub 2 --reply
```

And then run a benchmark with one (or more) synchronous requester(s)

```
$ nats bench test --pub 10 --request
03:04:56 Starting benchmark [msgs=100,000, msgsize=128 B, pubs=10, subs=0, js=false, stream=benchstream storage=memory, syncpub=false, pubbatch=100, jstimeout=30s, pull=false, pullbatch=100, request=true, reply=false, noqueue=false, maxackpending=-1, replicas=1, purge=false]
03:04:56 Benchmark in request/reply mode
Finished 2s [================================================] 100%
Finished 2s [================================================] 100%
Finished 2s [================================================] 100%
Finished 2s [================================================] 100%
Finished 2s [================================================] 100%
Finished 2s [================================================] 100%
Finished 2s [================================================] 100%
Finished 2s [================================================] 100%
Finished 2s [================================================] 100%
Finished 2s [================================================] 100%
Pub stats: 40,064 msgs/sec ~ 4.89 MB/sec
[1] 4,045 msgs/sec ~ 505.63 KB/sec (10000 msgs)
[2] 4,031 msgs/sec ~ 503.93 KB/sec (10000 msgs)
[3] 4,034 msgs/sec ~ 504.37 KB/sec (10000 msgs)
[4] 4,031 msgs/sec ~ 503.92 KB/sec (10000 msgs)
[5] 4,022 msgs/sec ~ 502.85 KB/sec (10000 msgs)
[6] 4,028 msgs/sec ~ 503.59 KB/sec (10000 msgs)
[7] 4,025 msgs/sec ~ 503.22 KB/sec (10000 msgs)
[8] 4,028 msgs/sec ~ 503.59 KB/sec (10000 msgs)
[9] 4,025 msgs/sec ~ 503.15 KB/sec (10000 msgs)
[10] 4,018 msgs/sec ~ 502.28 KB/sec (10000 msgs)
min 4,018 | avg 4,028 | max 4,045 | stddev 7 msgs
```

There are numerous other flags that can be set to configure size of messages, using push or pull JetStream consumers and much more, see `nats bench --help`.

### Latency

@@ -364,7 +431,7 @@ Here one can see a client connected and disconnected shortly after, several othe
If an account is running JetStream the `nats event` tool can also be used to look at JetStream advisories by passing
`--js-metric --js-advisory`

These events are JSON messages and can be viewed raw using `--json` or in Cloud Events format with `--cloudevent`,
These events are JSON messages and can be viewed raw using `--json` or in Cloud Events format with `--cloudevent`,
finally a short version of the messages can be shown:

```
@@ -487,10 +554,10 @@ Super Cluster:
c3
```

Additional to this various reports can be generated using `nats server report`, this allows one to list all connections and
Additional to this various reports can be generated using `nats server report`, this allows one to list all connections and
subscriptions across the entire cluster with filtering to limit the results by account etc.

Additional raw information in JSON format can be retrieved using the `nats server request` commands.
Additional raw information in JSON format can be retrieved using the `nats server request` commands.

### Schema Registry

16 changes: 8 additions & 8 deletions go.mod
View file
Original file line number Diff line number Diff line change
@@ -6,9 +6,8 @@ replace github.com/codahale/hdrhistogram => github.com/HdrHistogram/hdrhistogram

require (
github.com/AlecAivazis/survey/v2 v2.2.12
github.com/alecthomas/template v0.0.0-20190718012654-fb15b899a751 // indirect
github.com/HdrHistogram/hdrhistogram-go v1.1.0
github.com/alecthomas/units v0.0.0-20210208195552-ff826a37aa15 // indirect
github.com/codahale/hdrhistogram v1.1.0
github.com/dustin/go-humanize v1.0.0
github.com/emicklei/dot v0.15.0
github.com/fatih/color v1.12.0
@@ -18,19 +17,20 @@ require (
github.com/gosuri/uiprogress v0.0.1
github.com/guptarohit/asciigraph v0.5.2
github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51
github.com/nats-io/jsm.go v0.0.25
github.com/nats-io/nats-server/v2 v2.3.3-0.20210719165541-e8fea67b1a38
github.com/nats-io/nats.go v1.11.1-0.20210623165838-4b75fc59ae30
github.com/klauspost/compress v1.13.4
github.com/nats-io/jsm.go v0.0.26
github.com/nats-io/nats-server/v2 v2.4.1-0.20210907200628-874c79fe411f
github.com/nats-io/nats.go v1.12.0
github.com/nats-io/nuid v1.0.1
github.com/tylertreat/hdrhistogram-writer v0.0.0-20180430173243-73b8d31ba571
github.com/prometheus/client_golang v1.11.0
github.com/prometheus/common v0.26.0
github.com/tylertreat/hdrhistogram-writer v0.0.0-20210816161836-2e440612a39f
github.com/xeipuuv/gojsonpointer v0.0.0-20190905194746-02993c407bfb // indirect
github.com/xeipuuv/gojsonschema v1.2.0
github.com/xlab/tablewriter v0.0.0-20160610135559-80b567a11ad5
golang.org/x/crypto v0.0.0-20210616213533-5ff15b29337e
golang.org/x/term v0.0.0-20210422114643-f5beecf764ed
golang.org/x/text v0.3.6 // indirect
golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1 // indirect
google.golang.org/protobuf v1.24.0 // indirect
gopkg.in/alecthomas/kingpin.v2 v2.2.6
gopkg.in/yaml.v2 v2.4.0 // indirect
)
Loading