diff --git a/nats_server/monitoring.md b/nats_server/monitoring.md index d092be5..116f975 100644 --- a/nats_server/monitoring.md +++ b/nats_server/monitoring.md @@ -31,13 +31,33 @@ 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. + ## Monitoring endpoints -The following sections describe each supported monitoring endpoint: `varz`, `connz`, `routez`, and `subsz`. +The following sections describe each supported monitoring endpoint: `varz`, `connz`, `routez`, `subsz`, and `gatewayz`. +There are not any required arguments, however use of arguments can let you tailor monitoring to your environment +and tooling. -### /varz +### General Information -The endpoint http://localhost:8222/varz reports various general statistics. +The `/varz` endpoint returns general information about the server state and configuration. + +||| +|-|-| +| Endpoint | /varz | +| Success | 200 (OK) | +| Errors | 400 (Bad Request) | + +**Arguments:** + +N/A + +#### Example + +http://localhost:8222/varz + +#### Response ```json { @@ -90,14 +110,61 @@ The endpoint http://localhos } ``` -### /connz +### Connection Information -The endpoint http://localhost:8222/connz reports more detailed information on current connections. It uses a paging mechanism which defaults to 1024 connections. +The `/connz` endpoint reports more detailed information on current and recently closed connections. +It uses a paging mechanism which defaults to 1024 connections. -You can control these via URL arguments (limit and offset). For example: http://localhost:8222/connz?limit=1&offset=1. +||| +|-|-| +| Endpoint | /connz | +| Success | 200 (OK) | +| Errors | 400 (Bad Request) | + +**Arguments:** + +| Argument | Values | Description | +|-|-|-| +| sort | (*see sort options*) | Sorts the results. Default is connection ID. | +| 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. | +| cid | number, valid id | Return a connection by it's id | +| state | open \| *closed \| any | Return connections of partular state. Default is open.| + +*`*The server will hold the last 10,000 closed connections.`* + +**Sort options:** + +| Option | Sort by| +|-|-| +|cid | Connection ID | +|start | Connection start time, same as CID | +|subs | Number of subscriptions | +|pending | Amount of data in bytes waiting to be sent to client | +|msgs_to | Number of messages sent | +|msgs_from | Number of messages received | +|bytes_to | Number of bytes sent | +|bytes_from | Number of bytes received | +|last | Last activity | +|idle | Amount of inactivity | +|uptime | Lifetime of the connection | +|stop | Stop time for a closed connection | +|reason | Reason for a closed connection | + +#### Examples + +Get up to 1024 connections: http://localhost:8222/connz + +Control limit and offset: http://localhost:8222/connz?limit=16&offset=128. + +Get closed connection information: http://localhost: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. +#### Response + ```json { "server_id": "NACDVKFBUW4C4XA24OOT6L4MDP56MW76J5RJDFXG7HLABSB46DCMWCOW", @@ -155,11 +222,32 @@ You can also report detailed subscription information on a per connection basis } ``` -### /routez +### Route Information + +The `/routez` endpoint reports 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) | + +**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. -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://localhost:8222/routez?subs=1 + +#### Example + +* Get route information: http://localhost:8222/routez?subs=1 + +#### Response ```json { @@ -184,9 +272,30 @@ The `routez` endpoint does support the `subs` argument from the `/connz` endpoin } ``` -### /subsz +### Subscription information -The endpoint http://localhost:8222/subz reports detailed information about the current subscriptions and the routing data structure. +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 > 0 | Number of results to return. Default is 1024. | +| test | subject | Test whether a subsciption exists. | + +#### Example + +* Get subscription routing information: http://localhost:8222/subz + +#### Response ```json { @@ -201,6 +310,167 @@ The endpoint http://localho } ``` +### 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) | + +**Arguments:** + +| Argument | Values | Description | +|-|-|-| +| accs | true \| 1 \| false \| 0 | Include account information. Default is false. | +| gw_name | string | Return only remote gateways with this name. | +| acc_name | string | Limit the list of accounts to this account name. | + +#### Examples + +* Retrieve Gateway Information: http://localhost:8222/gatewayz + +#### Response + +```json +{ + "server_id": "NANVBOU62MDUWTXWRQ5KH3PSMYNCHCEUHQV3TW3YH7WZLS7FMJE6END6", + "now": "2019-07-24T18:02:55.597398-06:00", + "name": "region1", + "host": "2601:283:4601:1350:1895:efda:2010:95a1", + "port": 4501, + "outbound_gateways": { + "region2": { + "configured": true, + "connection": { + "cid": 7, + "ip": "127.0.0.1", + "port": 5500, + "start": "2019-07-24T18:02:48.765621-06:00", + "last_activity": "2019-07-24T18:02:48.765621-06:00", + "uptime": "6s", + "idle": "6s", + "pending_bytes": 0, + "in_msgs": 0, + "out_msgs": 0, + "in_bytes": 0, + "out_bytes": 0, + "subscriptions": 0, + "name": "NCXBIYWT7MV7OAQTCR4QTKBN3X3HDFGSFWTURTCQ22ZZB6NKKJPO7MN4" + } + }, + "region3": { + "configured": true, + "connection": { + "cid": 5, + "ip": "::1", + "port": 6500, + "start": "2019-07-24T18:02:48.764685-06:00", + "last_activity": "2019-07-24T18:02:48.764685-06:00", + "uptime": "6s", + "idle": "6s", + "pending_bytes": 0, + "in_msgs": 0, + "out_msgs": 0, + "in_bytes": 0, + "out_bytes": 0, + "subscriptions": 0, + "name": "NCVS7Q65WX3FGIL2YQRLI77CE6MQRWO2Y453HYVLNMBMTVLOKMPW7R6K" + } + } + }, + "inbound_gateways": { + "region2": [ + { + "configured": false, + "connection": { + "cid": 9, + "ip": "::1", + "port": 52029, + "start": "2019-07-24T18:02:48.76677-06:00", + "last_activity": "2019-07-24T18:02:48.767096-06:00", + "uptime": "6s", + "idle": "6s", + "pending_bytes": 0, + "in_msgs": 0, + "out_msgs": 0, + "in_bytes": 0, + "out_bytes": 0, + "subscriptions": 0, + "name": "NCXBIYWT7MV7OAQTCR4QTKBN3X3HDFGSFWTURTCQ22ZZB6NKKJPO7MN4" + } + } + ], + "region3": [ + { + "configured": false, + "connection": { + "cid": 4, + "ip": "::1", + "port": 52025, + "start": "2019-07-24T18:02:48.764577-06:00", + "last_activity": "2019-07-24T18:02:48.764994-06:00", + "uptime": "6s", + "idle": "6s", + "pending_bytes": 0, + "in_msgs": 0, + "out_msgs": 0, + "in_bytes": 0, + "out_bytes": 0, + "subscriptions": 0, + "name": "NCVS7Q65WX3FGIL2YQRLI77CE6MQRWO2Y453HYVLNMBMTVLOKMPW7R6K" + } + }, + { + "configured": false, + "connection": { + "cid": 8, + "ip": "127.0.0.1", + "port": 52026, + "start": "2019-07-24T18:02:48.766173-06:00", + "last_activity": "2019-07-24T18:02:48.766999-06:00", + "uptime": "6s", + "idle": "6s", + "pending_bytes": 0, + "in_msgs": 0, + "out_msgs": 0, + "in_bytes": 0, + "out_bytes": 0, + "subscriptions": 0, + "name": "NCKCYK5LE3VVGOJQ66F65KA27UFPCLBPX4N4YOPOXO3KHGMW24USPCKN" + } + } + ] + } +} +``` + ## 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.