server: create api to query persisted stats by date range

[cockroach-teamcity]

Exalate commented:

PR: cockroachdb/cockroach#69238

From release notes:

Added a new endpoint /_status/combinedstmts to retrieve persisted and in-memory statements from crdb_internal.statement_statistics and crdb_internal.transaction_statistics by aggregated_ts range. The request supports optional query string parameters start and end, which are the date range in unix time. The response returned is currently the response expected from /_status/statements. /_status/statements has also been updated to support the parameters combined, start, and end. If combined is true, then the statements endpoint will use /_status/combinedstmts with the optional parameters start and end. [#69238][#69238]

Jira Issue: DOC-1453

[jseldess]

@awoods187, I assigned this to SQL since it seems to be about SQL observability, but if this is a new api that we want to auto-generate docs for, we might need to move it to OX Observability where that's handled.

cc @mikeCRL and @itsbilal, who understand the autogeneration approach.

[awoods187]

@kevin-v-ngo can confirm but this looks like the new SQL observability items

[kevin-v-ngo]

Yes, this endpoint was created to support the new persisted stats experience in the console by SQL Obs team. The endpoint queries the new virtual table (combining in-memory and persisted stats) and allows filtering based on a specified start and end time.

Users should be able to use this endpoint for programatic access as well so we should probably have docs for this. What's the process for auto-generated docs?

[jseldess]

The "Cluster API" docs are the only ones auto-generated right now, as far as I know. For that, we use go-swagger to generate an Open API v2 spec from specially formatted code comments, then use a few other tools to transform the spec into Open API v3 and add example request for each endpoint, and finally use a tool called redoc to build it all as user-facing docs. The process is described here: https://cockroachlabs.atlassian.net/wiki/spaces/PROD/pages/1851719975/API+reference. However, it's just a first iteration, and I believe @itsbilal has a task to document how all of this works on the Eng side and map out a consistent process for other APIs. Bilal, can you please chime in?

cc @ianjevans, who probably needs to be involved for cloud apis as well. And @mikeCRL, who set this all up with Bilal.

[itsbilal]

Thanks for tagging me @jseldess ! I worked on the current process that you described (openAPI v2 spec generation etc), but given some of its shortcomings, we'd want to eventually move over to having an openAPI v3 spec as the single source of truth, off of which we auto-generate some server-side API code. For other APIs, it would make sense to start off with that approach to begin with. The migration of the existing CockroachDB API is very much a TODO item in the server team's roadmap at some point, and unfortunately I'm no longer in that team to be able to help out with that. But I can guide whoever takes that or any related work up.

[ianjevans]

cc'ing @erademacher who worked on adding the Cloud API autogen docs.