Standardize and Document System Account endpoints for $SYS.REQ.ACCOUNT.PING.<endpoint>

[caleblloyd]

Currently, there are 2 endpoints active under $SYS.REQ.ACCOUNT.PING.<endpoint> that were introduced in #3250

• $SYS.REQ.ACCOUNT.PING.STATZ - equivalent of HTTP endpoint /accstatz
• $SYS.REQ.ACCOUNT.PING.CONNS - I can't tell what this is for. [Added] account specific monitoring endpoint(s) #3250 mentions that it is a legacy endpoint, it has a listener, but no messages get replied on

These endpoints are not documented on the Available Events and Services page.

The confusing part about these endpoints being under $SYS.REQ.ACCOUNT.PING is how this acts for other account-related endpoints. For the following endpoints, PING will be treated as the Account Name for a lookup, and will not aggregate all accounts:

$SYS.REQ.ACCOUNT.PING.CONNZ
$SYS.REQ.ACCOUNT.PING.LEAFZ
$SYS.REQ.ACCOUNT.PING.SUBSZ
$SYS.REQ.ACCOUNT.PING.JSZ  // this actually could work by returning the equivalent of /jsz?accounts=1
$SYS.REQ.ACCOUNT.PING.INFO

Looking for feedback on the following 2 options to standardize:

1. Move $SYS.REQ.ACCOUNT.PING.STATZ to $SYS.REQ.SERVER.PING.ACCSTATZ to make this more closely align with HTTP endpoint
2. Keep $SYS.REQ.ACCOUNT.PING.STATZ where it is and document it

Another thing that could be considered, is that we could add support for parameter passing to these responders so that they are more closely able to return the data that the HTTP monitoring endpoints do. For example we could achieve getting all of the account JSZ data with nats req --header=accounts=1 $SYS.REQ.SERVER.PING.JSZ, and not have to add another request subject such as $SYS.REQ.ACCOUNT.PING.JSZ

/cc @bruth @wallyqs

[ripienaar]

There was a period of just seemingly randomly adding crazy sibjects. All for stabilising and documenting.

You wouldn’t “nats req” tbem most (and I think this one not) are under “nats server req” where all the various options they take are surfaced as easy to discover CLI flags.

[bruth]

I am in favor of changing to $SYS.REQ.SERVER.PING.ACCSTATZ for consistency and avoid confusion/conflict with the account name of PING.

I know this all is in the context of the system account, but the header suggestion makes me nervous as a general practice since permissions only apply to subjects. I think if there are variations of an endpoint desired, additional tokens could be added to make the request explicit.