-
Notifications
You must be signed in to change notification settings - Fork 3.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
server,docgen: enhance the API documentation
This commit makes three changes:
- it extends the API doc generator to recognize
annotations to distinguish “reserved”, “alpha” and “public” APIs
and report this level of support in the generated output.
- it makes it possible to annotate different levels of support
for different fields inside a single API payload. This makes
it possible to document that certain fields of public APIs
are “reserved”.
- it marks all the APIs as “reserved” except for the following three:
- `/health` which has been stabilized and is safely documentable.
- `/_status/nodes` and `/_status/hotranges` are marked
as “alpha” as requested by
@piyush-singh, to serve as example of how we could
document an API.
Note that some other API endpoints could probably be marked as “alpha”
but the upcoming release cycle will see the introduction of a new
namespace for public APIs, so we wish to not over-commit at this time.
Release note: None- Loading branch information
Showing
20 changed files
with
3,887 additions
and
1,098 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Large diffs are not rendered by default.
Oops, something went wrong.
Empty file.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
|
|
||
|
|
||
| <a name="cockroach.server.serverpb.HealthRequest"></a> | ||
| #### HealthRequest | ||
|
|
||
| HealthRequest requests a liveness or readiness check. | ||
|
|
||
| A liveness check is triggered via ready set to false. In this mode, | ||
| an empty response is returned immediately, that is, the caller merely | ||
| learns that the process is running. | ||
|
|
||
| A readiness check (ready == true) is suitable for determining whether | ||
| user traffic should be directed at a given node, for example by a load | ||
| balancer. In this mode, a successful response is returned only if the | ||
| node: | ||
|
|
||
| - is not in the process of shutting down or booting up (including | ||
| waiting for cluster bootstrap); | ||
| - is regarded as healthy by the cluster via the recent broadcast of | ||
| a liveness beacon. Absent either of these conditions, an error | ||
| code will result. | ||
|
|
||
| Support status: [public](#support-status) | ||
|
|
||
|
|
||
| | Field | Type | Label | Description | Support status | | ||
| | ----- | ---- | ----- | ----------- | -------------- | | ||
| | ready | [bool](#bool) | | ready specifies whether the client wants to know whether the target node is ready to receive traffic. If a node is unready, an error will be returned. | [public](#support-status) | | ||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
|
|
||
|
|
||
| <a name="cockroach.server.serverpb.HealthResponse"></a> | ||
| #### HealthResponse | ||
|
|
||
| HealthResponse is the response to HealthRequest. It currently does not | ||
| contain any information. | ||
|
|
||
| Support status: [public](#support-status) | ||
|
|
||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,139 @@ | ||
|
|
||
|
|
||
| <a name="cockroach.server.status.statuspb.NodeStatus"></a> | ||
| #### NodeStatus | ||
|
|
||
| NodeStatus records the most recent values of metrics for a node. | ||
|
|
||
| Support status: [alpha](#support-status) | ||
|
|
||
|
|
||
| | Field | Type | Label | Description | Support status | | ||
| | ----- | ---- | ----- | ----------- | -------------- | | ||
| | desc | [cockroach.roachpb.NodeDescriptor](#cockroach.roachpb.NodeDescriptor) | | desc is the node descriptor. | [reserved](#support-status) | | ||
| | build_info | [cockroach.build.Info](#cockroach.build.Info) | | build_info describes the `cockroach` executable file. | [alpha](#support-status) | | ||
| | started_at | [int64](#int64) | | started_at is the unix timestamp at which the node process was last started. | [alpha](#support-status) | | ||
| | updated_at | [int64](#int64) | | updated_at is the unix timestamp at which the node status record was last updated. | [alpha](#support-status) | | ||
| | metrics | [NodeStatus.MetricsEntry](#cockroach.server.status.statuspb.NodeStatus.MetricsEntry) | repeated | metrics contains the last sampled values for the node metrics. | [reserved](#support-status) | | ||
| | store_statuses | [StoreStatus](#cockroach.server.status.statuspb.StoreStatus) | repeated | store_statuses provides the store status payloads for all the stores on that node. | [reserved](#support-status) | | ||
| | args | [string](#string) | repeated | args is the list of command-line arguments used to last start the node. | [reserved](#support-status) | | ||
| | env | [string](#string) | repeated | env is the list of environment variables that influenced the node's configuration. | [reserved](#support-status) | | ||
| | latencies | [NodeStatus.LatenciesEntry](#cockroach.server.status.statuspb.NodeStatus.LatenciesEntry) | repeated | latencies is a map of nodeIDs to nanoseconds which is the latency between this node and the other node.<br><br>NOTE: this is deprecated and is only set if the min supported cluster version is >= VersionRPCNetworkStats. | [reserved](#support-status) | | ||
| | activity | [NodeStatus.ActivityEntry](#cockroach.server.status.statuspb.NodeStatus.ActivityEntry) | repeated | activity is a map of nodeIDs to network statistics from this node to other nodes. | [reserved](#support-status) | | ||
| | total_system_memory | [int64](#int64) | | total_system_memory is the total RAM available to the system (or, if detected, the memory available to the cgroup this process is in) in bytes. | [alpha](#support-status) | | ||
| | num_cpus | [int32](#int32) | | num_cpus is the number of logical CPUs as reported by the operating system on the host where the `cockroach` process is running. Note that this does not report the number of CPUs actually used by `cockroach`; this parameter is controlled separately. | [alpha](#support-status) | | ||
|
|
||
|
|
||
|
|
||
|
|
||
| <a name="cockroach.server.status.statuspb.NodeStatus.MetricsEntry"></a> | ||
| #### NodeStatus.MetricsEntry | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
| | Field | Type | Label | Description | Support status | | ||
| | ----- | ---- | ----- | ----------- | -------------- | | ||
| | key | [string](#string) | | | | | ||
| | value | [double](#double) | | | | | ||
|
|
||
|
|
||
|
|
||
|
|
||
| <a name="cockroach.server.status.statuspb.StoreStatus"></a> | ||
| #### StoreStatus | ||
|
|
||
| StoreStatus records the most recent values of metrics for a store. | ||
|
|
||
| Support status: [reserved](#support-status) | ||
|
|
||
|
|
||
| | Field | Type | Label | Description | Support status | | ||
| | ----- | ---- | ----- | ----------- | -------------- | | ||
| | desc | [cockroach.roachpb.StoreDescriptor](#cockroach.roachpb.StoreDescriptor) | | desc is the store descriptor. | [reserved](#support-status) | | ||
| | metrics | [StoreStatus.MetricsEntry](#cockroach.server.status.statuspb.StoreStatus.MetricsEntry) | repeated | metrics contains the last sampled values for the node metrics. | [reserved](#support-status) | | ||
|
|
||
|
|
||
|
|
||
|
|
||
| <a name="cockroach.server.status.statuspb.StoreStatus.MetricsEntry"></a> | ||
| #### StoreStatus.MetricsEntry | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
| | Field | Type | Label | Description | Support status | | ||
| | ----- | ---- | ----- | ----------- | -------------- | | ||
| | key | [string](#string) | | | | | ||
| | value | [double](#double) | | | | | ||
|
|
||
|
|
||
|
|
||
|
|
||
| <a name="cockroach.server.status.statuspb.NodeStatus.LatenciesEntry"></a> | ||
| #### NodeStatus.LatenciesEntry | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
| | Field | Type | Label | Description | Support status | | ||
| | ----- | ---- | ----- | ----------- | -------------- | | ||
| | key | [int32](#int32) | | | | | ||
| | value | [int64](#int64) | | | | | ||
|
|
||
|
|
||
|
|
||
|
|
||
| <a name="cockroach.server.status.statuspb.NodeStatus.ActivityEntry"></a> | ||
| #### NodeStatus.ActivityEntry | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
| | Field | Type | Label | Description | Support status | | ||
| | ----- | ---- | ----- | ----------- | -------------- | | ||
| | key | [int32](#int32) | | | | | ||
| | value | [NodeStatus.NetworkActivity](#cockroach.server.status.statuspb.NodeStatus.NetworkActivity) | | | | | ||
|
|
||
|
|
||
|
|
||
|
|
||
| <a name="cockroach.server.status.statuspb.NodeStatus.NetworkActivity"></a> | ||
| #### NodeStatus.NetworkActivity | ||
|
|
||
|
|
||
|
|
||
| Support status: [reserved](#support-status) | ||
|
|
||
|
|
||
| | Field | Type | Label | Description | Support status | | ||
| | ----- | ---- | ----- | ----------- | -------------- | | ||
| | incoming | [int64](#int64) | | in bytes | [reserved](#support-status) | | ||
| | outgoing | [int64](#int64) | | in bytes | [reserved](#support-status) | | ||
| | latency | [int64](#int64) | | in nanoseconds | [reserved](#support-status) | | ||
|
|
||
|
|
||
|
|
||
|
|
||
| <a name="cockroach.server.serverpb.NodesResponse.LivenessByNodeIdEntry"></a> | ||
| #### NodesResponse.LivenessByNodeIdEntry | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
| | Field | Type | Label | Description | Support status | | ||
| | ----- | ---- | ----- | ----------- | -------------- | | ||
| | key | [int32](#int32) | | | | | ||
| | value | [cockroach.kv.kvserver.liveness.livenesspb.NodeLivenessStatus](#cockroach.kv.kvserver.liveness.livenesspb.NodeLivenessStatus) | | | | | ||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
|
|
||
|
|
||
| <a name="cockroach.server.serverpb.NodesRequest"></a> | ||
| #### NodesRequest | ||
|
|
||
| NodesRequest requests a copy of the node information as known to gossip | ||
| and the KV layer. | ||
|
|
||
| Support status: [alpha](#support-status) | ||
|
|
||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
|
|
||
|
|
||
| <a name="cockroach.server.serverpb.NodesResponse"></a> | ||
| #### NodesResponse | ||
|
|
||
| NodesResponse describe the nodes in the cluster. | ||
|
|
||
| Support status: [alpha](#support-status) | ||
|
|
||
|
|
||
| | Field | Type | Label | Description | Support status | | ||
| | ----- | ---- | ----- | ----------- | -------------- | | ||
| | nodes | [cockroach.server.status.statuspb.NodeStatus](#cockroach.server.status.statuspb.NodeStatus) | repeated | nodes carries the status payloads for all nodes in the cluster. | [alpha](#support-status) | | ||
| | liveness_by_node_id | [NodesResponse.LivenessByNodeIdEntry](#cockroach.server.serverpb.NodesResponse.LivenessByNodeIdEntry) | repeated | liveness_by_node_id maps each node ID to a liveness status. | [reserved](#support-status) | | ||
|
|
||
|
|
Oops, something went wrong.