diff --git a/nats_server/monitoring.md b/nats_server/monitoring.md index 116f975..f6096a2 100644 --- a/nats_server/monitoring.md +++ b/nats_server/monitoring.md @@ -1,6 +1,15 @@ ## Monitoring NATS -To monitor the NATS messaging system, `nats-server` provides a lightweight HTTP server on a dedicated monitoring port. The monitoring server provides several endpoints, including [varz](#/varz), [connz](#/connz), [routez](#/routez), and [subsz](#/subz). All endpoints return a JSON object. +To monitor the NATS messaging system, `nats-server` provides a lightweight HTTP server on a dedicated monitoring port. +The monitoring server provides several endpoints, providing statistics and other information about the following: + +* [General Server Information](#General-Information) +* [Connections](#Connection-Information) +* [Routing](#Route-Information) +* [Subscription Routing](#Subscription-Routing-Information) +* [Gateways](#Gateway-Information) + +All endpoints return a JSON object. The NATS monitoring endpoints support JSONP and CORS, making it easy to create single page monitoring web applications. @@ -21,7 +30,7 @@ $ nats-server -m 8222 [4528] 2019/06/01 20:09:58.573090 [INF] nats-server is ready ``` -To test, run `nats-server -m 8222`, then go to http://localhost:8222/ +To test, run `nats-server -m 8222`, then go to http://demo.nats.io:8222/ ### Enable monitoring from the configuration file @@ -31,7 +40,7 @@ You can also enable monitoring using the configuration file as follows: http_port: 8222 ``` -For example, to monitor this server locally, the endpoint would be http://localhost:8222/varz reports various general statistics. +For example, to monitor this server locally, the endpoint would be http://demo.nats.io:8222/varz reports various general statistics. ## Monitoring endpoints @@ -43,19 +52,20 @@ and tooling. The `/varz` endpoint returns general information about the server state and configuration. -||| -|-|-| -| Endpoint | /varz | -| Success | 200 (OK) | -| Errors | 400 (Bad Request) | +**Endpoint:** `http://server:port/varz` -**Arguments:** +| Result | Return Code | +|-|-| +| Success | 200 (OK) | +| Error | 400 (Bad Request) | + +#### Arguments N/A #### Example -http://localhost:8222/varz +http://demo.nats.io:8222/varz #### Response @@ -115,13 +125,14 @@ N/A The `/connz` endpoint reports more detailed information on current and recently closed connections. It uses a paging mechanism which defaults to 1024 connections. -||| -|-|-| -| Endpoint | /connz | -| Success | 200 (OK) | -| Errors | 400 (Bad Request) | +**Endpoint:** `http://server:port/connz` -**Arguments:** +| Result | Return Code | +|-|-| +| Success | 200 (OK) | +| Error | 400 (Bad Request) | + +#### Arguments | Argument | Values | Description | |-|-|-| @@ -129,13 +140,13 @@ It uses a paging mechanism which defaults to 1024 connections. | auth | true\|1\|false\|0 | Include username. Default is false. | | subs | true\|1\|false\|0 | Include subscriptions. Default is false. | | offset | number > 0 | Pagination offset. Default is 0. | -| limit | number > 1 | Number of results to return. Default is 1024. | +| limit | number > 0 | Number of results to return. Default is 1024. | | cid | number, valid id | Return a connection by it's id | -| state | open \| *closed \| any | Return connections of partular state. Default is open.| +| state | open \| *closed \| any | Return connections of partular state. Default is open. | *`*The server will hold the last 10,000 closed connections.`* -**Sort options:** +##### Sort Options | Option | Sort by| |-|-| @@ -155,13 +166,13 @@ It uses a paging mechanism which defaults to 1024 connections. #### Examples -Get up to 1024 connections: http://localhost:8222/connz +Get up to 1024 connections: http://demo.nats.io:8222/connz -Control limit and offset: http://localhost:8222/connz?limit=16&offset=128. +Control limit and offset: http://demo.nats.io:8222/connz?limit=16&offset=128. -Get closed connection information: http://localhost:8222/connz?state=closed. +Get closed connection information: http://demo.nats.io:8222/connz?state=closed. -You can also report detailed subscription information on a per connection basis using subs=1. For example: http://localhost:8222/connz?limit=1&offset=1&subs=1. +You can also report detailed subscription information on a per connection basis using subs=1. For example: http://demo.nats.io:8222/connz?limit=1&offset=1&subs=1. #### Response @@ -224,28 +235,27 @@ You can also report detailed subscription information on a per connection basis ### Route Information -The `/routez` endpoint reports reports information on active routes for a cluster. +The `/routez` endpoint reports information on active routes for a cluster. Routes are expected to be low, so there is no paging mechanism with this endpoint. -||| -|-|-| -| Endpoint | /routez | -| Success | 200 (OK) | -| Errors | 400 (Bad Request) | +**Endpoint:** `http://server:port/routez` -**Arguments:** +| Result | Return Code | +|-|-| +| Success | 200 (OK) | +| Error | 400 (Bad Request) | + +#### Arguments | Argument | Values | Description | |-|-|-| | subs | true \| 1 \| false \| 0 | Include internal subscriptions. Default is false.| -The endpoint http://localhost:8222/routez reports information on active routes for a cluster. Routes are expected to be low, so there is no paging mechanism with this endpoint. - -As noted above, the `routez` endpoint does support the `subs` argument from the `/connz` endpoint. For example: http://localhost:8222/routez?subs=1 +As noted above, the `routez` endpoint does support the `subs` argument from the `/connz` endpoint. For example: http://demo.nats.io:8222/routez?subs=1 #### Example -* Get route information: http://localhost:8222/routez?subs=1 +* Get route information: http://demo.nats.io:8222/routez?subs=1 #### Response @@ -272,17 +282,18 @@ As noted above, the `routez` endpoint does support the `subs` argument from the } ``` -### Subscription information +### Subscription Routing Information -The `/subsz` endpoint reports detailed information about the current subscriptions and the routing data structure. It is not normally used. +The `/subz` endpoint reports detailed information about the current subscriptions and the routing data structure. It is not normally used. -||| +**Endpoint:** `http://server:port/subz` + +| Result | Return Code | |-|-| -| Endpoint | /subsz | -| Success | 200 (OK) | -| Errors | 400 (Bad Request) | +| Success | 200 (OK) | +| Error | 400 (Bad Request) | -**Arguments:** +#### Arguments | Argument | Values | Description | |-|-|-| @@ -293,7 +304,7 @@ The `/subsz` endpoint reports detailed information about the current subscriptio #### Example -* Get subscription routing information: http://localhost:8222/subz +* Get subscription routing information: http://demo.nats.io:8222/subsz #### Response @@ -310,41 +321,19 @@ The `/subsz` endpoint reports detailed information about the current subscriptio } ``` -### Subscription Routing Information - -The `/subsz` endpoint reports detailed information about the current subscriptions and the routing data structure. It is not normally used. - -||| -|-|-| -| Endpoint | /subsz | -| Success | 200 (OK) | -| Errors | 400 (Bad Request) | - -**Arguments:** - -| Argument | Values | Description | -|-|-|-| -| subs | true \| 1 \| false \| 0 | Include subscriptions. Default is false. | -| offset | integer > 0 | Pagination offset. Default is 0. | -| limit | integer > 1 | Number of results to return. Default is 1024. | -| test | subject | Test whether a subsciption exists. | - -#### Example - -* Get subscription routing information: http://localhost:8222/subz - ### Gateway Information The `/gatewayz` endpoint reports information about gateways used to create a NATS supercluster. Like routes, the number of gateways are expected to be low, so there is no paging mechanism with this endpoint. -||| -|-|-| -| Endpoint | /gatewayz | -| Success | 200 (OK) | -| Errors | 400 (Bad Request) | +**Endpoint:** `http://server:port/gatewayz` -**Arguments:** +| Result | Return Code | +|-|-| +| Success | 200 (OK) | +| Error | 400 (Bad Request) | + +#### Arguments | Argument | Values | Description | |-|-|-| @@ -354,7 +343,7 @@ Like routes, the number of gateways are expected to be low, so there is no pagin #### Examples -* Retrieve Gateway Information: http://localhost:8222/gatewayz +* Retrieve Gateway Information: http://demo.nats.io:8222/gatewayz #### Response @@ -471,20 +460,20 @@ Like routes, the number of gateways are expected to be low, so there is no pagin } ``` -## Creating monitoring applications +## Creating Monitoring Applications NATS monitoring endpoints support [JSONP](https://en.wikipedia.org/wiki/JSONP) and [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing#How_CORS_works). You can easily create single page web applications for monitoring. To do this you simply pass the `callback` query parameter to any endpoint. For example: ```sh -http://localhost:8222/connz?callback=cb +http://demo.nats.io:8222/connz?callback=cb ``` Here is a JQuery example implementation: ```javascript -$.getJSON('http://localhost:8222/connz?callback=?', function(data) { +$.getJSON('http://demo.nats.io:8222/connz?callback=?', function(data) { console.log(data); });