taigrr/nats.docs
1
0
Fork 0
mirror of https://github.com/taigrr/nats.docs synced 2025-01-18 04:03:23 -08:00
Code Issues Projects Releases Wiki Activity

wip

Browse Source
This commit is contained in:
Alberto Ricart 2019-05-15 14:53:38 -05:00
parent dd445372d2
commit ce705a504b
5 changed files with 540 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

258
nats_docker/README.md Normal file
View File

@ -0,0 +1,258 @@
## NATS Server Containerization
The NATS server is provided as a Docker image on [Docker Hub](https://hub.docker.com/_/nats/) that you can run using the Docker daemon. The NATS server Docker image is extremely lightweight, coming in under 10 MB in size.
Synadia actively maintains and supports the NATS server Docker image.
### Usage
To use the Docker container image, install Docker and pull the public image:
```sh
> docker pull nats
```
Run the NATS server image:
```sh
> docker run -d --name nats-main nats
```
By default the NATS server exposes multiple ports:
- 4222 is for clients.
- 8222 is an HTTP management port for information reporting.
- 6222 is a routing port for clustering.
- Use -p or -P to customize.
For example:
```sh
$ docker run -d --name nats-main nats
[INF] Starting nats-server version 0.6.6
[INF] Starting http monitor on port 8222
[INF] Listening for route connections on 0.0.0.0:6222
[INF] Listening for client connections on 0.0.0.0:4222
[INF] nats-server is ready
```
To run with the ports exposed on the host:
```sh
> docker run -d -p 4222:4222 -p 6222:6222 -p 8222:8222 --name nats-main nats
```
To run a second server and cluster them together:
```sh
> docker run -d --name=nats-2 --link nats-main nats --routes=nats-route://ruser:T0pS3cr3t@nats-main:6222
```
**NOTE** Since the Docker image protects routes using credentials we need to provide them above. Extracted [from Docker image configuration](https://github.com/nats-io/nats-docker/blob/master/amd64/nats-server.conf#L16-L20)
```ascii
# Routes are protected, so need to use them with --routes flag
# e.g. --routes=nats-route://ruser:T0pS3cr3t@otherdockerhost:6222
authorization {
user: ruser
password: T0pS3cr3t
timeout: 2
}
```
To verify the routes are connected:
```sh
$ docker run -d --name=nats-2 --link nats-main nats --routes=nats-route://ruser:T0pS3cr3t@nats-main:6222 -DV
[INF] Starting nats-server version 0.6.6
[INF] Starting http monitor on port 8222
[INF] Listening for route connections on :6222
[INF] Listening for client connections on 0.0.0.0:4222
[INF] nats-server is ready
[DBG] Trying to connect to route on nats-main:6222
[DBG] 172.17.0.52:6222 - rid:1 - Route connection created
[DBG] 172.17.0.52:6222 - rid:1 - Route connect msg sent
[DBG] 172.17.0.52:6222 - rid:1 - Registering remote route "ee35d227433a738c729f9422a59667bb"
[DBG] 172.17.0.52:6222 - rid:1 - Route sent local subscriptions
```
## Clustering With Docker
Below is are a couple examples of how to setup nats-server cluster using Docker. We put 3 different configurations (one per nats-server server) under a folder named conf as follows:
```ascii
|-- conf
|-- nats-server-A.conf
|-- nats-server-B.conf
|-- nats-server-C.conf
```
Each one of those files have the following content below: (Here I am using ip 192.168.59.103 as an example, so just replace with the proper ip from your server)
### Example 1: Setting up a cluster on 3 different servers provisioned beforehand
In this example, the three servers are started with config files that know about the other servers.
#### nats-server-A
```ascii
# Cluster Server A
port: 7222
cluster {
host: '0.0.0.0'
port: 7244
routes = [
nats-route://192.168.59.103:7246
nats-route://192.168.59.103:7248
]
}
```
#### nats-server-B
```ascii
# Cluster Server B
port: 8222
cluster {
host: '0.0.0.0'
port: 7246
routes = [
nats-route://192.168.59.103:7244
nats-route://192.168.59.103:7248
]
}
```
#### nats-server-C
```ascii
# Cluster Server C
port: 9222
cluster {
host: '0.0.0.0'
port: 7248
routes = [
nats-route://192.168.59.103:7244
nats-route://192.168.59.103:7246
]
}
```
To start the containers, on each one of your servers, you should be able to start the nats-server image as follows:
```sh
docker run -it -p 0.0.0.0:7222:7222 -p 0.0.0.0:7244:7244 --rm -v $(pwd)/conf/nats-server-A.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 7222 -D -V
```
```
docker run -it -p 0.0.0.0:8222:8222 -p 0.0.0.0:7246:7246 --rm -v $(pwd)/conf/nats-server-B.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 8222 -D -V
```
```
docker run -it -p 0.0.0.0:9222:9222 -p 0.0.0.0:7248:7248 --rm -v $(pwd)/conf/nats-server-C.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 9222 -D -V
```
### Example 2: Setting a nats-server cluster one by one
In this scenario:
- We bring up A and get its ip (nats-route://192.168.59.103:7244)
- Then create B and then use address of A in its configuration.
- Get the address of B nats-route://192.168.59.104:7246 and create C and use the addresses of A and B.
First, we create the Node A and start up a nats-server server with the following config:
```ascii
# Cluster Server A
port: 4222
cluster {
host: '0.0.0.0'
port: 7244
}
```
```sh
docker run -it -p 0.0.0.0:4222:4222 -p 0.0.0.0:7244:7244 --rm -v $(pwd)/conf/nats-server-A.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 4222 -D -V
```
Then we proceed to create the next node. We realize that the first node has ip:port as `192.168.59.103:7244` so we add this to the routes configuration as follows:
```ascii
# Cluster Server B
port: 4222
cluster {
host: '0.0.0.0'
port: 7244
routes = [
nats-route://192.168.59.103:7244
]
}
```
Then start server B:
```sh
docker run -it -p 0.0.0.0:4222:4222 -p 0.0.0.0:7244:7244 --rm -v $(pwd)/conf/nats-server-B.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 4222 -D -V
```
Finally, we create another Node C. We now know the routes of A and B so we can add it to its configuration:
```ascii
# Cluster Server C
port: 4222
cluster {
host: '0.0.0.0'
port: 7244
routes = [
nats-route://192.168.59.103:7244
nats-route://192.168.59.104:7244
]
}
```
Then start it:
```sh
docker run -it -p 0.0.0.0:4222:4222 -p 0.0.0.0:7244:7244 --rm -v $(pwd)/conf/nats-server-C.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 9222 -D -V
```
### Testing the Clusters
Now, the following should work: make a subscription to Node A then publish to Node C. You should be able to to receive the message without problems.
```sh
nats-sub -s "nats://192.168.59.103:7222" hello &
nats-pub -s "nats://192.168.59.105:7222" hello world
[#1] Received on [hello] : 'world'
# GNATSD on Node C logs:
[1] 2015/06/23 05:20:31.100032 [TRC] 192.168.59.103:7244 - rid:2 - <<- [MSG hello RSID:8:2 5]
# GNATSD on Node A logs:
[1] 2015/06/23 05:20:31.100600 [TRC] 10.0.2.2:51007 - cid:8 - <<- [MSG hello 2 5]
```
## Tutorial
See the [NATS Docker tutorial](tutorial.md) for more instructions on using the NATS server Docker image.

59
nats_docker/tutorial.md Normal file
View File

@ -0,0 +1,59 @@
## NATS Docker Tutorial
In this tutorial you run the [NATS server Docker image](https://hub.docker.com/_/nats/). The Docker image provides an instance of the [NATS Server](/documentation/server/gnatsd-intro/). Synadia actively maintains and supports the gnatsd Docker image. The NATS image is only 6 MB in size.
**1. Set up Docker.**
See [Get Started with Docker](http://docs.docker.com/mac/started/) for guidance.
The easiest way to run Docker is to use the [Docker Toolbox](http://docs.docker.com/mac/step_one/).
**2. Run the gnatsd Docker image.**
```sh
> docker run -p 4222:4222 -p 8222:8222 -p 6222:6222 --name gnatsd -ti nats:latest
```
**3. Verify that the NATS server is running.**
You should see the following:
```sh
Unable to find image 'nats:latest' locally
latest: Pulling from library/nats
2d3d00b0941f: Pull complete
24bc6bd33ea7: Pull complete
Digest: sha256:47b825feb34e545317c4ad122bd1a752a3172bbbc72104fc7fb5e57cf90f79e4
Status: Downloaded newer image for nats:latest
```
Followed by this, indicating that the NATS server is running:
```sh
[1] 2017/06/28 18:34:19.605144 [INF] Starting nats-server version 0.9.6
[1] 2017/06/28 18:34:19.605191 [INF] Starting http monitor on 0.0.0.0:8222
[1] 2017/06/28 18:34:19.605286 [INF] Listening for client connections on 0.0.0.0:4222
[1] 2017/06/28 18:34:19.605312 [INF] Server is ready
[1] 2017/06/28 18:34:19.608756 [INF] Listening for route connections on 0.0.0.0:6222
```
Notice how quickly the NATS server Docker image downloads. It is a mere 6 MB in size.
**4. Test the NATS server to verify it is running.**
An easy way to test the client connection port is through using telnet.
```sh
> telnet localhost 4222
```
Expected result:
```sh
Trying ::1...
Connected to localhost.
Escape character is '^]'.
INFO {"server_id":"YMeTi2z178lM5SG302YgH2","version":"0.9.6","go":"go1.7.4","host":"0.0.0.0","port":4222,"auth_required":false,"ssl_required":false,"tls_required":false,"tls_verify":false,"max_payload":1048576}
```
You can also test the monitoring endpoint, viewing `http://localhost:8222` with a browser.

5
nats_tools/README.md Normal file
View File

@ -0,0 +1,5 @@
## NATS Tools
The NATS Ecosystem has many tools, some interesting tools include:
- [NATS TOP (statistics)](nats_top/README.md)

81
nats_tools/nats_top/README.md Normal file
View File

@ -0,0 +1,81 @@
## NATS TOP
[nats-top](https://github.com/nats-io/nats-top) is a [top](http://man7.org/linux/man-pages/man1/top.1.html)-like tool for monitoring nats-server servers.
The nats-top tool provides a dynamic real-time view of a NATS server. nats-top can display a variety of system summary information about the NATS server, such as subscription, pending bytes, number of messages, and more, in real time. For example:
```sh
nats-top
nats-server version 0.6.4 (uptime: 31m42s)
Server:
Load: CPU: 0.8% Memory: 5.9M Slow Consumers: 0
In: Msgs: 34.2K Bytes: 3.0M Msgs/Sec: 37.9 Bytes/Sec: 3389.7
Out: Msgs: 68.3K Bytes: 6.0M Msgs/Sec: 75.8 Bytes/Sec: 6779.4
Connections: 4
HOST CID SUBS PENDING MSGS_TO MSGS_FROM BYTES_TO BYTES_FROM LANG VERSION SUBSCRIPTIONS
127.0.0.1:56134 2 5 0 11.6K 11.6K 1.1M 905.1K go 1.1.0 foo, hello
127.0.1.1:56138 3 1 0 34.2K 0 3.0M 0 go 1.1.0 _INBOX.a96f3f6853616154d23d1b5072
127.0.0.1:56144 4 5 0 11.2K 11.1K 873.5K 1.1M go 1.1.0 foo, hello
127.0.0.1:56151 5 8 0 11.4K 11.5K 1014.6K 1.0M go 1.1.0 foo, hello
```
## Installation
nats-top can be installed using `go get`. For example:
```sh
go get github.com/nats-io/nats-top
```
NOTE: You may have to run the above command as user `sudo` depending on your setup. If you receive an error that you cannot install nats-top because your $GOPATH is not set, when in fact it is set, use command `sudo -E go get github.com/nats-io/nats-top` to install nats-top. The `-E` flag tells sudo to preserve the current user's environment.
## Usage
Once installed, nats-top can be run with the command `nats-top` and optional arguments.
```sh
nats-top [-s server] [-m monitor] [-n num_connections] [-d delay_in_secs] [-sort by]
```
## Options
Optional arguments inclde the following:
| Option | Description |
|-----------------------|-----------------------------------------------|
| `-m monitor` | Monitoring http port from nats-server. |
| `-n num_connections` | Limit the connections requested to the server (default 1024). |
| `-d delay_in_secs` | Screen refresh interval (default 1 second). |
| `-sort by` | Field to use for sorting the connections (see below). |
## Commands
While in nats-top view, you can use the following commands.
### option
Use the `o<option>` command to set the primary sort key to the `<option>` value. The option value can be one of the following: `cid`, `subs`, `pending`, `msgs_to`, `msgs_from`, `bytes_to`, `bytes_from`, `lang`, `version`.
You can also set the sort option on the command line using the `-sort` flag. For example: `nats-top -sort bytes_to`.
### limit
Use the `n<limit>` command to set the sample size of connections to request from the server.
You can also set this on the command line using the `-n num_connections` flag. For example: `nats-top -n 1`.
Note that if `n<limit>` is used in conjunction with `-sort`, the server will respect both options allowing queries such as the following: Query for the connection with largest number of subscriptions: `nats-top -n 1 -sort subs`.
### s, ? and q Commands
Use the `s` command to toggle displaying connection subscriptions.
Use the `?` command to show help message with options.
Use the `q` command to quit nats-top.
### Tutorial
For a walkthrough with `nats-top` check out the [tutorial](/documentation/additional_documentation/nats-top).

137
nats_tools/nats_top/tutorial.md Normal file
View File

@ -0,0 +1,137 @@
## NATS TOP Tutorial
You can use [nats-top](natstop.md) to monitor in realtime NATS server connections and message statistics.
#### Prerequisites
- [Set up your Go environment](/documentation/additional_documentation/go-install/)
- [Installed the NATS server](/documentation/managing_the_server/installing/)
#### 1. Install nats-top
```sh
% go get github.com/nats-io/nats-top
```
You may need to run the following instead:
```sh
% sudo -E go get github.com/nats-io/nats-top
```
#### 2. Start the NATS server with monitoring enabled
```sh
% nats-server -m 8222
```
#### 3. Start nats-top
```sh
% nats-top
```
Result:
```sh
nats-server version 0.6.6 (uptime: 2m2s)
Server:
Load: CPU: 0.0% Memory: 6.3M Slow Consumers: 0
In: Msgs: 0 Bytes: 0 Msgs/Sec: 0.0 Bytes/Sec: 0
Out: Msgs: 0 Bytes: 0 Msgs/Sec: 0.0 Bytes/Sec: 0
Connections: 0
HOST CID SUBS PENDING MSGS_TO MSGS_FROM BYTES_TO BYTES_FROM LANG VERSION
```
#### 4. Run NATS client programs
Run some NATS client programs and exchange messages.
For the best experience, you will want to run multiple subscribers, at least 2 or 3. Refer to the [example pub-sub clients](/documentation/additional_documentation/nats-pub-sub).
#### 5. Check nats-top for statistics
```sh
nats-server version 0.6.6 (uptime: 30m51s)
Server:
Load: CPU: 0.0% Memory: 10.3M Slow Consumers: 0
In: Msgs: 56 Bytes: 302 Msgs/Sec: 0.0 Bytes/Sec: 0
Out: Msgs: 98 Bytes: 512 Msgs/Sec: 0.0 Bytes/Sec: 0
Connections: 3
HOST CID SUBS PENDING MSGS_TO MSGS_FROM BYTES_TO BYTES_FROM LANG VERSION
::1:58651 6 1 0 52 0 260 0 go 1.1.0
::1:58922 38 1 0 21 0 105 0 go 1.1.0
::1:58953 39 1 0 21 0 105 0 go 1.1.0
```
#### 6. Sort nats-top statistics
In nats-top, enter the command `o` followed by the option, such as `bytes_to`. You see that nats-top sorts the BYTES_TO column in ascending order.
```sh
nats-server version 0.6.6 (uptime: 45m40s)
Server:
Load: CPU: 0.0% Memory: 10.4M Slow Consumers: 0
In: Msgs: 81 Bytes: 427 Msgs/Sec: 0.0 Bytes/Sec: 0
Out: Msgs: 154 Bytes: 792 Msgs/Sec: 0.0 Bytes/Sec: 0
sort by [bytes_to]:
Connections: 3
HOST CID SUBS PENDING MSGS_TO MSGS_FROM BYTES_TO BYTES_FROM LANG VERSION
::1:59259 83 1 0 4 0 20 0 go 1.1.0
::1:59349 91 1 0 2 0 10 0 go 1.1.0
::1:59342 90 1 0 0 0 0 0 go 1.1.0
```
#### 7. Use different sort options
Use some different sort options to explore nats-top, such as:
`cid`, `subs`, `pending`, `msgs_to`, `msgs_from`, `bytes_to`, `bytes_from`, `lang`, `version`
You can also set the sort option on the command line using the `-sort` flag. For example: `nats-top -sort bytes_to`.
#### 8. Display the registered subscriptions.
In nats-top, enter the command `s` to toggle displaying connection subscriptions. When enabled, you see the subscription subject in nats-top table:
```sh
nats-server version 0.6.6 (uptime: 1h2m23s)
Server:
Load: CPU: 0.0% Memory: 10.4M Slow Consumers: 0
In: Msgs: 108 Bytes: 643 Msgs/Sec: 0.0 Bytes/Sec: 0
Out: Msgs: 185 Bytes: 1.0K Msgs/Sec: 0.0 Bytes/Sec: 0
Connections: 3
HOST CID SUBS PENDING MSGS_TO MSGS_FROM BYTES_TO BYTES_FROM LANG VERSION SUBSCRIPTIONS
::1:59708 115 1 0 6 0 48 0 go 1.1.0 foo.bar
::1:59758 122 1 0 1 0 8 0 go 1.1.0 foo
::1:59817 124 1 0 0 0 0 0 go 1.1.0 foo
```
#### 9. Quit nats-top
Use the `q` command to quit nats-top.
#### 10. Restart nats-top with a specified query
For example, to query for the connection with largest number of subscriptions:
```sh
% nats-top -n 1 -sort subs
```
Result: nats-top displays only the client connection with the largest number of subscriptions:
```sh
nats-server version 0.6.6 (uptime: 1h7m0s)
Server:
Load: CPU: 0.0% Memory: 10.4M Slow Consumers: 0
In: Msgs: 109 Bytes: 651 Msgs/Sec: 0.0 Bytes/Sec: 0
Out: Msgs: 187 Bytes: 1.0K Msgs/Sec: 0.0 Bytes/Sec: 0
Connections: 3
HOST CID SUBS PENDING MSGS_TO MSGS_FROM BYTES_TO BYTES_FROM LANG VERSION
::1:59708 115 1 0 6 0 48 0 go 1.1.0
```