From 4dc2d7f0b7d61192f53fee3173429e374144059f Mon Sep 17 00:00:00 2001 From: Colin Sullivan Date: Sat, 27 Feb 2021 17:30:51 -0700 Subject: [PATCH] update docs Signed-off-by: Colin Sullivan --- jetstream/administration/administration.md | 2 +- jetstream/administration/consumers.md | 2 +- jetstream/administration/streams.md | 68 +++++++++++++++------- jetstream/clustering/administration.md | 4 +- jetstream/getting_started/using_docker.md | 23 ++------ jetstream/getting_started/using_source.md | 4 +- 6 files changed, 58 insertions(+), 45 deletions(-) diff --git a/jetstream/administration/administration.md b/jetstream/administration/administration.md index 1abfecb..4585bbe 100644 --- a/jetstream/administration/administration.md +++ b/jetstream/administration/administration.md @@ -1,6 +1,6 @@ ## Administration and Usage from the CLI -Once the server is running it's time to use the management tool. This can be downloaded from the [GitHub Release Page](https://github.com/nats-io/natscli/releases/) or you can use the `synadia/jsm:latest` docker image. On OS X homebrew can be used to install the latest version: +Once the server is running it's time to use the management tool. This can be downloaded from the [GitHub Release Page](https://github.com/nats-io/natscli/releases/) or you can use the `natsio/nats-box:latest` docker image. On OS X homebrew can be used to install the latest version: ```nohighlight $ brew tap nats-io/nats-tools diff --git a/jetstream/administration/consumers.md b/jetstream/administration/consumers.md index 3506676..9526c4d 100644 --- a/jetstream/administration/consumers.md +++ b/jetstream/administration/consumers.md @@ -156,7 +156,7 @@ More details about the `State` section will be shown later when discussing the a #### Consuming Pull-Based Consumers -Pull-based Consumers require you to specifically ask for messages and ack them, typically you would do this with the client library `Request()` feature, but the `jsm` utility has a helper: +Pull-based Consumers require you to specifically ask for messages and ack them, typically you would do this with the client library `Request()` feature, but the `nats` utility has a helper: First we ensure we have a message: diff --git a/jetstream/administration/streams.md b/jetstream/administration/streams.md index 72e8689..1fcaf4c 100644 --- a/jetstream/administration/streams.md +++ b/jetstream/administration/streams.md @@ -42,7 +42,7 @@ Statistics: You can get prompted interactively for missing information as above, or do it all on one command. Pressing `?` in the CLI will help you map prompts to CLI options: ``` -$ nats str add ORDERS --subjects "ORDERS.*" --ack --max-msgs=-1 --max-bytes=-1 --max-age=1y --storage file --retention limits --max-msg-size=-1 --discard old +nats str add ORDERS --subjects "ORDERS.*" --ack --max-msgs=-1 --max-bytes=-1 --max-age=1y --storage file --retention limits --max-msg-size=-1 --discard old --dupe-window="0s" --replicas 1 ``` Additionally one can store the configuration in a JSON file, the format of this is the same as `$ nats str info ORDERS -j | jq .config`: @@ -68,26 +68,29 @@ Information about the configuration of the Stream can be seen, and if you did no ```nohighlight $ nats str info ORDERS -Information for Stream ORDERS +Information for Stream ORDERS created 2021-02-27T16:49:36-07:00 Configuration: Subjects: ORDERS.* - No Acknowledgements: false + Acknowledgements: true Retention: File - Limits Replicas: 1 - Maximum Messages: -1 - Maximum Bytes: -1 - Maximum Age: 8760h0m0s - Maximum Consumers: -1 + Discard Policy: Old + Duplicate Window: 2m0s + Maximum Messages: unlimited + Maximum Bytes: unlimited + Maximum Age: 1y0d0h0m0s + Maximum Message Size: unlimited + Maximum Consumers: unlimited -Statistics: +State: - Messages: 0 - Bytes: 0 B - FirstSeq: 0 - LastSeq: 0 - Active Consumers: 0 + Messages: 0 + Bytes: 0 B + FirstSeq: 0 + LastSeq: 0 + Active Consumers: 0 ``` Most commands that show data as above support `-j` to show the results as JSON: @@ -105,14 +108,20 @@ $ nats str info ORDERS -j "max_msgs": -1, "max_bytes": -1, "max_age": 31536000000000000, + "max_msg_size": -1, "storage": "file", - "num_replicas": 1 + "discard": "old", + "num_replicas": 1, + "duplicate_window": 120000000000 }, - "stats": { + "created": "2021-02-27T23:49:36.700424Z", + "state": { "messages": 0, "bytes": 0, "first_seq": 0, + "first_ts": "0001-01-01T00:00:00Z", "last_seq": 0, + "last_ts": "0001-01-01T00:00:00Z", "consumer_count": 0 } } @@ -128,14 +137,29 @@ A stream can be copied into another, which also allows the configuration of the $ nats str cp ORDERS ARCHIVE --subjects "ORDERS_ARCVHIVE.*" --max-age 2y Stream ORDERS was created -Information for Stream ARCHIVE +Information for Stream ORDERS created 2021-02-27T16:52:46-07:00 Configuration: - Subjects: ORDERS_ARCVHIVE.* -... - Maximum Age: 17520h0m0s -... + Subjects: ORDERS_ARCHIVE.* + Acknowledgements: true + Retention: File - Limits + Replicas: 1 + Discard Policy: Old + Duplicate Window: 2m0s + Maximum Messages: unlimited + Maximum Bytes: unlimited + Maximum Age: 2y0d0h0m0s + Maximum Message Size: unlimited + Maximum Consumers: unlimited + +State: + + Messages: 0 + Bytes: 0 B + FirstSeq: 0 + LastSeq: 0 + Active Consumers: 0 ``` #### Editing @@ -208,7 +232,7 @@ To delete all data in a stream use `purge`: ```nohighlight $ nats str purge ORDERS -f ... -Statistics: +State: Messages: 0 Bytes: 0 B @@ -231,5 +255,5 @@ Finally for demonstration purposes, you can also delete the whole Stream and rec ``` $ nats str rm ORDERS -f -$ nats str add ORDERS --subjects "ORDERS.*" --ack --max-msgs=-1 --max-bytes=-1 --max-age=1y --storage file --retention limits --max-msg-size=-1 +$ nats str add ORDERS --subjects "ORDERS.*" --ack --max-msgs=-1 --max-bytes=-1 --max-age=1y --storage file --retention limits --max-msg-size=-1 --discard old --dupe-window="0s" --replicas 1 ``` diff --git a/jetstream/clustering/administration.md b/jetstream/clustering/administration.md index 7c05e83..ef213fd 100644 --- a/jetstream/clustering/administration.md +++ b/jetstream/clustering/administration.md @@ -8,12 +8,12 @@ Within an account there are operations and reports that show where users data is ## Creating clustered streams -When adding a stream using the `nats` CLI the number of replicas will be asked, when you choose a number more than 1, (we suggest 1, 3 or 5), the data will be stored o multiple nodes in your cluster using the RAFT protocol as above. +When adding a stream using the `nats` CLI the number of replicas will be asked, when you choose a number more than 1, (we suggest 1, 3 or 5), the data will be stored o multiple nodes in your cluster using the RAFT protocol as above. The replica count must be less than the maximum number of servers. ```nohighlight $ nats str add ORDERS --replicas 3 .... -Information for Stream ORDERS_4 created 2021-02-05T12:07:34+01:00 +Information for Stream ORDERS created 2021-02-05T12:07:34+01:00 .... Configuration: .... diff --git a/jetstream/getting_started/using_docker.md b/jetstream/getting_started/using_docker.md index a16549e..f46a7fa 100644 --- a/jetstream/getting_started/using_docker.md +++ b/jetstream/getting_started/using_docker.md @@ -1,29 +1,17 @@ # Using Docker -The `synadia/jsm:latest` docker image contains both the JetStream enabled NATS Server and the `nats` utility this guide covers. +The `synadia/nats-box:latest` docker image contains the `nats` utility this guide covers. -In one window start JetStream: +In one window start a JetStream enabled nats server: ``` -$ docker run -ti -p 4222:4222 --name jetstream synadia/jsm:latest server -[1] 2020/01/20 12:44:11.752465 [INF] Starting nats-server version 2.2.0-beta -[1] 2020/01/20 12:44:11.752694 [INF] Git commit [19dc3eb] -[1] 2020/01/20 12:44:11.752875 [INF] Starting JetStream -[1] 2020/01/20 12:44:11.753692 [INF] ----------- JETSTREAM (Beta) ----------- -[1] 2020/01/20 12:44:11.753794 [INF] Max Memory: 1.46 GB -[1] 2020/01/20 12:44:11.753822 [INF] Max Storage: 1.00 TB -[1] 2020/01/20 12:44:11.753860 [INF] Store Directory: "/tmp/jetstream" -[1] 2020/01/20 12:44:11.753893 [INF] ---------------------------------------- -[1] 2020/01/20 12:44:11.753988 [INF] JetStream state for account "$G" recovered -[1] 2020/01/20 12:44:11.754148 [INF] Listening for client connections on 0.0.0.0:4222 -[1] 2020/01/20 12:44:11.754279 [INF] Server id is NDYX5IMGF2YLX6RC4WLZA7T3JGHPZR2RNCCIFUQBT6C4TP27Z6ZIC73V -[1] 2020/01/20 12:44:11.754308 [INF] Server is ready +$ docker run --network host -p 4222:4222 nats -js ``` And in another log into the utilities: ``` -$ docker run -ti --link jetstream synadia/jsm:latest +$ docker run -ti --network host synadia/nats-box ``` This shell has the `nats` utility and all other NATS cli tools used in the rest of this guide. @@ -34,6 +22,7 @@ Now skip to the `Administer JetStream` section. You can join a JetStream instance to your [NGS](https://synadia.com/ngs/pricing) account, first we need a credential for testing JetStream: +You'll want to do this outside of docker to keep the credentials that are generated. ``` $ nsc add user -a YourAccount --name leafnode --expiry 1M ``` @@ -42,7 +31,7 @@ You'll get a credential file somewhere like `~/.nkeys/creds/synadia/YourAccount/ ``` $ docker run -ti -v ~/.nkeys/creds/synadia/YourAccount/leafnode.creds:/leafnode.creds --name jetstream synadia/jsm:latest server -[1] 2020/01/20 12:44:11.752465 [INF] Starting nats-server version 2.2.0-beta +[1] 2020/01/20 12:44:11.752465 [INF] Starting nats-server version 2.2.0 ... [1] 2020/01/20 12:55:01.849033 [INF] Connected leafnode to "connect.ngs.global" ``` diff --git a/jetstream/getting_started/using_source.md b/jetstream/getting_started/using_source.md index b21eb8a..7b7e821 100644 --- a/jetstream/getting_started/using_source.md +++ b/jetstream/getting_started/using_source.md @@ -17,7 +17,7 @@ Starting the server you can use the `-js` flag. This will setup the server to re ``` $ ./nats-server -js -[16928] 2019/12/04 19:16:29.596968 [INF] Starting nats-server version 2.2.0-beta +[16928] 2019/12/04 19:16:29.596968 [INF] Starting nats-server version 2.2.0 [16928] 2019/12/04 19:16:29.597056 [INF] Git commit [not set] [16928] 2019/12/04 19:16:29.597072 [INF] Starting JetStream [16928] 2019/12/04 19:16:29.597444 [INF] ----------- JETSTREAM (Beta) ----------- @@ -35,7 +35,7 @@ You can override the storage directory if you want. ``` $ ./nats-server -js -sd /tmp/test -[16943] 2019/12/04 19:20:00.874148 [INF] Starting nats-server version 2.2.0-beta +[16943] 2019/12/04 19:20:00.874148 [INF] Starting nats-server version 2.2.0 [16943] 2019/12/04 19:20:00.874247 [INF] Git commit [not set] [16943] 2019/12/04 19:20:00.874273 [INF] Starting JetStream [16943] 2019/12/04 19:20:00.874605 [INF] ----------- JETSTREAM (Beta) -----------