# System Events

NATS servers leverage [Accounts](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/accounts) support and generate events such as:

* account connect/disconnect
* authentication errors
* server shutdown
* server stat summary

In addition the server supports a limited number of requests that can be used to query for account connections, server stat summaries, and pinging servers in the cluster.

These events are enabled by configuring `system_account` and [subscribing/requesting](#available-events-and-services) using a *system account* user.

[Accounts](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/accounts) are used so that subscriptions from your applications, say `>`, do not receive system events and vice versa. Using accounts requires either:

* [Configuring authentication locally](#local-configuration) and listing one of the accounts in `system_account`
* Or by using decentralized authentication and authorization via [jwt](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/jwt) as shown in this [Tutorial](https://docs.nats.io/running-a-nats-service/configuration/sys_accounts/sys_accounts). In this case `system_account` contains the account public key.

N.B. The default global account `$G` does not publish advisories.

## Available Events and Services

### System Account

The system account publishes messages under well known subject patterns.

Server initiated events:

* `$SYS.ACCOUNT.<id>.CONNECT` (client connects)
* `$SYS.ACCOUNT.<id>.DISCONNECT` (client disconnects)
* `$SYS.ACCOUNT.<id>.SERVER.CONNS` (connections for an account changed)
* `$SYS.SERVER.<id>.CLIENT.AUTH.ERR` (authentication error)
* `$SYS.SERVER.<id>.STATSZ` (stats summary)

In addition other tools with system account privileges, can initiate requests (Examples can be found [here](https://docs.nats.io/running-a-nats-service/configuration/sys_accounts#system-services)):

* `$SYS.REQ.SERVER.<id>.STATSZ` (request server stat summary)
* `$SYS.REQ.SERVER.PING` (discover servers - will return multiple messages)

[Monitoring endpoints](https://docs.nats.io/running-a-nats-service/configuration/monitoring) as listed in the table below are accessible as system services using the following subject pattern:

* `$SYS.REQ.SERVER.<id>.<endpoint-name>` (request server monitoring endpoint corresponding to endpoint name.)
* `$SYS.REQ.SERVER.PING.<endpoint-name>` (from all server, request server monitoring endpoint corresponding to endpoint name - will return multiple messages)

| Endpoint                                                                                                        | Endpoint Name |
| --------------------------------------------------------------------------------------------------------------- | ------------- |
| [General Server Information](https://docs.nats.io/running-a-nats-service/monitoring#general-information)        | `VARZ`        |
| [Connections](https://docs.nats.io/running-a-nats-service/monitoring#connection-information)                    | `CONNZ`       |
| [Routing](https://docs.nats.io/running-a-nats-service/monitoring#route-information)                             | `ROUTEZ`      |
| [Gateways](https://docs.nats.io/running-a-nats-service/monitoring#gateway-information)                          | `GATEWAYZ`    |
| [Leaf Nodes](https://docs.nats.io/running-a-nats-service/monitoring#leaf-nodes-information)                     | `LEAFZ`       |
| [Subscription Routing](https://docs.nats.io/running-a-nats-service/monitoring#subscription-routing-information) | `SUBSZ`       |
| [JetStream](https://docs.nats.io/running-a-nats-service/monitoring#jetstream-information)                       | `JSZ`         |
| [Accounts](https://docs.nats.io/running-a-nats-service/monitoring#account-information)                          | `ACCOUNTZ`    |
| [Health](https://docs.nats.io/nats_admin/monitoring#health)                                                     | `HEALTHZ`     |

* `"$SYS.REQ.ACCOUNT.<account-id>.<endpoint-name>`(from all server, request account specific monitoring endpoint corresponding to account id and endpoint name - will return multiple messages)

| Endpoint                                                                                                        | Endpoint Name |
| --------------------------------------------------------------------------------------------------------------- | ------------- |
| [Connections](https://docs.nats.io/running-a-nats-service/monitoring#connection-information)                    | `CONNZ`       |
| [Leaf Nodes](https://docs.nats.io/running-a-nats-service/monitoring#leaf-nodes-information)                     | `LEAFZ`       |
| [Subscription Routing](https://docs.nats.io/running-a-nats-service/monitoring#subscription-routing-information) | `SUBSZ`       |
| [JetStream](https://docs.nats.io/running-a-nats-service/monitoring#jetstream-information)                       | `JSZ`         |
| [Account](https://docs.nats.io/running-a-nats-service/monitoring#account-information)                           | `INFO`        |

Servers like `nats-account-server` publish system account messages when a claim is updated, the nats-server listens for them, and updates its account information accordingly:

* `$SYS.ACCOUNT.<id>.CLAIMS.UPDATE`

With these few messages you can build useful monitoring tools:

* health/load of your servers
* client connects/disconnects
* account connections
* authentication errors

## Local Configuration

To make use of System events, just using accounts, your configuration can look like this:

```
accounts: {
    USERS: {
        users: [
            {user: a, password: a}
        ]
    },
    SYS: { 
        users: [
            {user: admin, password: changeit}
           ]
    },
}
system_account: SYS
```

Please note that applications now have to authenticate such that a connection can be associated with an account. In this example username and password were chosen for simplicity of the demonstration. Subscribe to all system events like this `nats sub -s nats://admin:changeit@localhost:4222 ">"` and observe what happens when you do something like `nats pub -s "nats://a:a@localhost:4222" foo bar`. Examples on how to use system services can be found [here](https://docs.nats.io/running-a-nats-service/configuration/sys_accounts#system-services).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nats.io/running-a-nats-service/configuration/sys_accounts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.