Full - Cockroach — ContextQMD

Certificates

GET /_status/certificates/{node_id}

Certificates retrieves a copy of the TLS certificates.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string		node_id is a string so that "local" can be used to specify that no forwarding is necessary.	reserved

Response Parameters

Field	Type	Label	Description	Support status
certificates	CertificateDetails	repeated		reserved

CertificateDetails

Field	Type	Label	Description	Support status
type	CertificateDetails.CertificateType			reserved
error_message	string		"error_message" and "data" are mutually exclusive.	reserved
fields	CertificateDetails.Fields	repeated		reserved

CertificateDetails.Fields

Field	Type	Label	Support status
issuer	string		reserved
subject	string		reserved
valid_from	int64		reserved
valid_until	int64		reserved
addresses	string	repeated	reserved
signature_algorithm	string		reserved
public_key	string		reserved
key_usage	string	repeated	reserved
extended_key_usage	string	repeated	reserved

Details

GET /_status/details/{node_id}

Details retrieves details about the nodes in the cluster.

Support status: reserved

Request Parameters

DetailsRequest requests a nodes details. Note: this does not check readiness. Use the Health RPC for that purpose.

Field	Type	Label	Description	Support status
node_id	string		node_id is a string so that "local" can be used to specify that no forwarding is necessary.	reserved
redact	bool		redact, if true, requests redaction of sensitive data away from the API response.	reserved

Response Parameters

Field	Type	Support status
node_id	int32	reserved
address	cockroach.util.UnresolvedAddr	reserved
build_info	cockroach.build.Info	reserved
system_info	SystemInfo	reserved
sql_address	cockroach.util.UnresolvedAddr	reserved

SystemInfo

SystemInfo contains information about the host system.

Field	Type	Label	Description	Support status
system_info	string		system_info is the output from `uname -a`	reserved
kernel_info	string		kernel_info is the output from `uname -r`.	reserved

Regions

RegionsRequest retrieves all available regions.

Support status: reserved

Request Parameters

RegionsRequest requests all available regions.

Response Parameters

RegionsResponse describes the available regions.

Field	Type	Label	Description	Support status
regions	RegionsResponse.RegionsEntry	repeated		reserved

RegionsResponse.RegionsEntry

Field	Type	Label	Description	Support status
key	string
value	RegionsResponse.Region

RegionsResponse.Region

Field	Type	Label	Description	Support status
zones	string	repeated		reserved

NodesList

NodesList returns all available nodes with their addresses.

Support status: reserved

Request Parameters

NodesListRequest requests list of all nodes. The nodes are KV nodes when the cluster is a single tenant cluster or the host cluster in case of multi-tenant clusters. The nodes are SQL instances in case of multi-tenant clusters.

Field	Type	Label	Description	Support status
redact	bool		redact, if true, requests redaction of sensitive data away from the API response.	reserved

Response Parameters

NodesListResponse contains a list of all nodes with their addresses. The nodes are KV nodes when the cluster is a single tenant cluster or the host cluster in case of multi-tenant clusters. The nodes are SQL instances in case of multi-tenant clusters.

Field	Type	Label	Description	Support status
nodes	NodeDetails	repeated	nodes contains a list of NodeDetails. Each individual node within the list is a SQL node in case of a tenant server and KV nodes in case of a KV server.	reserved

NodeDetails

Field	Type	Description	Support status
node_id	int32	node_id is a unique identifier for the node. This corresponds to SQL instance ID for a tenant server and KV node id for for a KV server.	reserved
address	cockroach.util.UnresolvedAddr	address is the RPC address for a KV node. This will be set to null for a tenant server node.	reserved
sql_address	cockroach.util.UnresolvedAddr	sql_address is the SQL address for a node.	reserved

Nodes

GET /_status/nodes

Nodes returns status info for all commissioned nodes. Decommissioned nodes are not included, except in rare cases where the node doing the decommissioning crashed before completing the operation. In these cases, the decommission operation can be rerun to clean up the status entry.

Don't introduce additional usages of this RPC. See #50707 for more details. The underlying response type is something we're looking to get rid of.

Support status: alpha

Request Parameters

NodesRequest requests a copy of the node information as known to gossip and the KV layer.

Field	Type	Label	Description	Support status
redact	bool		redact, if true, requests redaction of sensitive data away from the API response.	reserved

Response Parameters

NodesResponse describe the nodes in the cluster.

Field	Type	Label	Description	Support status
nodes	cockroach.server.status.statuspb.NodeStatus	repeated	nodes carries the status payloads for all nodes in the cluster.	alpha
liveness_by_node_id	NodesResponse.LivenessByNodeIdEntry	repeated	liveness_by_node_id maps each node ID to a liveness status.	reserved

NodeStatus

NodeStatus records the most recent values of metrics for a node.

Field	Type	Label	Description	Support status
desc	cockroach.roachpb.NodeDescriptor		desc is the node descriptor.	reserved
build_info	cockroach.build.Info		build_info describes the `cockroach` executable file.	alpha
started_at	int64		started_at is the unix timestamp at which the node process was last started.	alpha
updated_at	int64		updated_at is the unix timestamp at which the node status record was last updated.	alpha
metrics	NodeStatus.MetricsEntry	repeated	metrics contains the last sampled values for the node metrics.	reserved
store_statuses	StoreStatus	repeated	store_statuses provides the store status payloads for all the stores on that node.	reserved
args	string	repeated	args is the list of command-line arguments used to last start the node.	reserved
env	string	repeated	env is the list of environment variables that influenced the node's configuration.	reserved
latencies	NodeStatus.LatenciesEntry	repeated	latencies is a map of nodeIDs to nanoseconds which is the latency between this node and the other node.

NOTE: this is deprecated and is only set if the min supported cluster version is >= VersionRPCNetworkStats. | reserved | | activity | NodeStatus.ActivityEntry | repeated | activity is a map of nodeIDs to network statistics from this node to other nodes. | reserved | | total_system_memory | 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 | | num_cpus | int32 | | num_cpus is the number of logical CPUs as reported by the operating system on the host where the cockroach process is running. This reflects the physical CPU count and does not account for container/cgroup limits. See num_vcpus for container-aware CPU allocation. | alpha | | num_vcpus | double | | num_vcpus is the number of vCPUs allocated to the process by the container orchestrator (e.g., Kubernetes, Docker) based on cgroup CPU quota/period. This represents the platform CPU allocation and is independent of GOMAXPROCS runtime tuning. Falls back to num_cpus if no container limits are configured. Supports fractional values (e.g., 1.5 for Kubernetes CPU limits like "1500m"). | alpha |

NodeStatus.MetricsEntry

Field	Type	Label	Description	Support status
key	string
value	double

StoreStatus

StoreStatus records the most recent values of metrics for a store.

Field	Type	Label	Description	Support status
desc	cockroach.roachpb.StoreDescriptor		desc is the store descriptor.	reserved
metrics	StoreStatus.MetricsEntry	repeated	metrics contains the last sampled values for the node metrics.	reserved

StoreStatus.MetricsEntry

Field	Type	Label	Description	Support status
key	string
value	double

NodeStatus.LatenciesEntry

Field	Type	Label	Description	Support status
key	int32
value	int64

NodeStatus.ActivityEntry

Field	Type	Label	Description	Support status
key	int32
value	NodeStatus.NetworkActivity

NodeStatus.NetworkActivity

Field	Type	Label	Description	Support status
latency	int64		in nanoseconds	reserved

NodesResponse.LivenessByNodeIdEntry

Field	Type	Label	Description	Support status
key	int32
value	cockroach.kv.kvserver.liveness.livenesspb.NodeLivenessStatus

Node

GET /_status/nodes/{node_id}

Node retrieves details about a single node.

Support status: alpha

Request Parameters

Field	Type	Label	Description	Support status
node_id	string		node_id is a string so that "local" can be used to specify that no forwarding is necessary.	reserved
redact	bool		redact, if true, requests redaction of sensitive data away from the API response.	reserved

Response Parameters

NodeStatus records the most recent values of metrics for a node.

Field	Type	Label	Description	Support status
desc	cockroach.roachpb.NodeDescriptor		desc is the node descriptor.	reserved
build_info	cockroach.build.Info		build_info describes the `cockroach` executable file.	alpha
started_at	int64		started_at is the unix timestamp at which the node process was last started.	alpha
updated_at	int64		updated_at is the unix timestamp at which the node status record was last updated.	alpha
metrics	NodeStatus.MetricsEntry	repeated	metrics contains the last sampled values for the node metrics.	reserved
store_statuses	StoreStatus	repeated	store_statuses provides the store status payloads for all the stores on that node.	reserved
args	string	repeated	args is the list of command-line arguments used to last start the node.	reserved
env	string	repeated	env is the list of environment variables that influenced the node's configuration.	reserved
latencies	NodeStatus.LatenciesEntry	repeated	latencies is a map of nodeIDs to nanoseconds which is the latency between this node and the other node.

NodeStatus.MetricsEntry

Field	Type	Label	Description	Support status
key	string
value	double

StoreStatus

StoreStatus records the most recent values of metrics for a store.

Field	Type	Label	Description	Support status
desc	cockroach.roachpb.StoreDescriptor		desc is the store descriptor.	reserved
metrics	StoreStatus.MetricsEntry	repeated	metrics contains the last sampled values for the node metrics.	reserved

StoreStatus.MetricsEntry

Field	Type	Label	Description	Support status
key	string
value	double

NodeStatus.LatenciesEntry

Field	Type	Label	Description	Support status
key	int32
value	int64

NodeStatus.ActivityEntry

Field	Type	Label	Description	Support status
key	int32
value	NodeStatus.NetworkActivity

NodeStatus.NetworkActivity

Field	Type	Label	Description	Support status
latency	int64		in nanoseconds	reserved

NodesUI

GET /_status/nodes_ui

Support status: reserved

Request Parameters

NodesRequest requests a copy of the node information as known to gossip and the KV layer.

Field	Type	Label	Description	Support status
redact	bool		redact, if true, requests redaction of sensitive data away from the API response.	reserved

Response Parameters

NodesResponse describe the nodes in the cluster.

Field	Type	Label	Description	Support status
nodes	NodeResponse	repeated	nodes carries the status payloads for all nodes in the cluster.	alpha
liveness_by_node_id	NodesResponseExternal.LivenessByNodeIdEntry	repeated	liveness_by_node_id maps each node ID to a liveness status.	reserved

NodeResponse

NodeStatus records the most recent values of metrics for a node.

Field	Type	Label	Description	Support status
desc	NodeDescriptor		desc is the node descriptor.	reserved
build_info	cockroach.build.Info		build_info describes the `cockroach` executable file.	alpha
started_at	int64		started_at is the unix timestamp at which the node process was last started.	alpha
updated_at	int64		updated_at is the unix timestamp at which the node status record was last updated.	alpha
metrics	NodeResponse.MetricsEntry	repeated	metrics contains the last sampled values for the node metrics.	reserved
store_statuses	StoreStatus	repeated	store_statuses provides the store status payloads for all the stores on that node.	reserved
args	string	repeated	args is the list of command-line arguments used to last start the node. args should only be visible by the Admin role.	reserved
env	string	repeated	env is the list of environment variables that influenced the node's configuration. env should only be visible by the Admin role.	reserved
latencies	NodeResponse.LatenciesEntry	repeated	latencies is a map of nodeIDs to nanoseconds which is the latency between this node and the other node.

NOTE: this is deprecated and is only set if the min supported cluster version is >= VersionRPCNetworkStats. | reserved | | activity | NodeResponse.ActivityEntry | repeated | activity is a map of nodeIDs to network statistics from this node to other nodes. | reserved | | total_system_memory | 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 | | num_cpus | 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 | | num_vcpus | double | | num_vcpus is the number of provisioned vCPUs as reported by cgroups or the operating system. | reserved |

NodeDescriptor

NodeDescriptor holds details on node physical/network topology.

Field	Type	Label	Description	Support status
node_id	int32			reserved
address	cockroach.util.UnresolvedAddr		address should only be visible by the Admin role.	reserved
attrs	cockroach.roachpb.Attributes		attrs should only be visible by the Admin role.	reserved
locality	Locality			reserved
ServerVersion	Version			reserved
build_tag	string			reserved
started_at	int64			reserved
locality_address	cockroach.roachpb.LocalityAddress	repeated	locality_address should only be visible by the Admin role.	reserved
cluster_name	string			reserved
sql_address	cockroach.util.UnresolvedAddr		The SQL address. If empty, indicates that the base address field is also used to accept SQL connections. sql_address should only be visible by the Admin role.	reserved

Locality

Locality is an ordered set of key value Tiers that describe a node's location. The tier keys should be the same across all nodes.

Field	Type	Label	Description	Support status
tiers	Tier	repeated		reserved

Tier

Tier represents one level of the locality hierarchy.

Field	Type	Label	Description	Support status
key	string		Key is the name of tier and should match all other nodes.	reserved
value	string		Value is node specific value corresponding to the key.	reserved

Version

Field	Type	Description	Support status
major_val	int32	The names "major" and "minor" are reserved in C in some platforms (e.g. FreeBSD).	reserved
minor_val	int32		reserved
patch	int32	Note that patch is a placeholder and will always be zero.	reserved
internal	int32	The internal version is used to introduce migrations during the development cycle. They are subversions that are never the end versions of a release, i.e. users of stable, public release will only use binaries with the internal version set to 0.	reserved

NodeResponse.MetricsEntry

Field	Type	Label	Description	Support status
key	string
value	double

StoreStatus

StoreStatus records the most recent values of metrics for a store.

Field	Type	Label	Description	Support status
desc	StoreDescriptor		desc is the store descriptor.	reserved
metrics	StoreStatus.MetricsEntry	repeated	metrics contains the last sampled values for the node metrics.	reserved

StoreDescriptor

StoreDescriptor holds store information including store attributes, node descriptor and store capacity.

Field	Type	Support status
store_id	int32	reserved
attrs	cockroach.roachpb.Attributes	reserved
node	NodeDescriptor	reserved
capacity	cockroach.roachpb.StoreCapacity	reserved
properties	cockroach.roachpb.StoreProperties	reserved

NodeDescriptor

NodeDescriptor holds details on node physical/network topology.

Field	Type	Label	Description	Support status
node_id	int32			reserved
address	cockroach.util.UnresolvedAddr		address should only be visible by the Admin role.	reserved
attrs	cockroach.roachpb.Attributes		attrs should only be visible by the Admin role.	reserved
locality	Locality			reserved
ServerVersion	Version			reserved
build_tag	string			reserved
started_at	int64			reserved
locality_address	cockroach.roachpb.LocalityAddress	repeated	locality_address should only be visible by the Admin role.	reserved
cluster_name	string			reserved
sql_address	cockroach.util.UnresolvedAddr		The SQL address. If empty, indicates that the base address field is also used to accept SQL connections. sql_address should only be visible by the Admin role.	reserved

StoreStatus.MetricsEntry

Field	Type	Label	Description	Support status
key	string
value	double

NodeResponse.LatenciesEntry

Field	Type	Label	Description	Support status
key	int32
value	int64

NodeResponse.ActivityEntry

Field	Type	Label	Description	Support status
key	int32
value	NodeResponse.NetworkActivity

NodeResponse.NetworkActivity

Field	Type	Label	Description	Support status
latency	int64		in nanoseconds	reserved

NodesResponseExternal.LivenessByNodeIdEntry

Field	Type	Label	Description	Support status
key	int32
value	cockroach.kv.kvserver.liveness.livenesspb.NodeLivenessStatus

NodeUI

GET /_status/nodes_ui/{node_id}

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string		node_id is a string so that "local" can be used to specify that no forwarding is necessary.	reserved
redact	bool		redact, if true, requests redaction of sensitive data away from the API response.	reserved

Response Parameters

NodeStatus records the most recent values of metrics for a node.

Field	Type	Label	Description	Support status
desc	NodeDescriptor		desc is the node descriptor.	reserved
build_info	cockroach.build.Info		build_info describes the `cockroach` executable file.	alpha
started_at	int64		started_at is the unix timestamp at which the node process was last started.	alpha
updated_at	int64		updated_at is the unix timestamp at which the node status record was last updated.	alpha
metrics	NodeResponse.MetricsEntry	repeated	metrics contains the last sampled values for the node metrics.	reserved
store_statuses	StoreStatus	repeated	store_statuses provides the store status payloads for all the stores on that node.	reserved
args	string	repeated	args is the list of command-line arguments used to last start the node. args should only be visible by the Admin role.	reserved
env	string	repeated	env is the list of environment variables that influenced the node's configuration. env should only be visible by the Admin role.	reserved
latencies	NodeResponse.LatenciesEntry	repeated	latencies is a map of nodeIDs to nanoseconds which is the latency between this node and the other node.

NodeDescriptor

NodeDescriptor holds details on node physical/network topology.

Field	Type	Label	Description	Support status
node_id	int32			reserved
address	cockroach.util.UnresolvedAddr		address should only be visible by the Admin role.	reserved
attrs	cockroach.roachpb.Attributes		attrs should only be visible by the Admin role.	reserved
locality	Locality			reserved
ServerVersion	Version			reserved
build_tag	string			reserved
started_at	int64			reserved
locality_address	cockroach.roachpb.LocalityAddress	repeated	locality_address should only be visible by the Admin role.	reserved
cluster_name	string			reserved
sql_address	cockroach.util.UnresolvedAddr		The SQL address. If empty, indicates that the base address field is also used to accept SQL connections. sql_address should only be visible by the Admin role.	reserved

Locality

Locality is an ordered set of key value Tiers that describe a node's location. The tier keys should be the same across all nodes.

Field	Type	Label	Description	Support status
tiers	Tier	repeated		reserved

Tier

Tier represents one level of the locality hierarchy.

Field	Type	Label	Description	Support status
key	string		Key is the name of tier and should match all other nodes.	reserved
value	string		Value is node specific value corresponding to the key.	reserved

Version

Field	Type	Description	Support status
major_val	int32	The names "major" and "minor" are reserved in C in some platforms (e.g. FreeBSD).	reserved
minor_val	int32		reserved
patch	int32	Note that patch is a placeholder and will always be zero.	reserved
internal	int32	The internal version is used to introduce migrations during the development cycle. They are subversions that are never the end versions of a release, i.e. users of stable, public release will only use binaries with the internal version set to 0.	reserved

NodeResponse.MetricsEntry

Field	Type	Label	Description	Support status
key	string
value	double

StoreStatus

StoreStatus records the most recent values of metrics for a store.

Field	Type	Label	Description	Support status
desc	StoreDescriptor		desc is the store descriptor.	reserved
metrics	StoreStatus.MetricsEntry	repeated	metrics contains the last sampled values for the node metrics.	reserved

StoreDescriptor

StoreDescriptor holds store information including store attributes, node descriptor and store capacity.

Field	Type	Support status
store_id	int32	reserved
attrs	cockroach.roachpb.Attributes	reserved
node	NodeDescriptor	reserved
capacity	cockroach.roachpb.StoreCapacity	reserved
properties	cockroach.roachpb.StoreProperties	reserved

NodeDescriptor

NodeDescriptor holds details on node physical/network topology.

Field	Type	Label	Description	Support status
node_id	int32			reserved
address	cockroach.util.UnresolvedAddr		address should only be visible by the Admin role.	reserved
attrs	cockroach.roachpb.Attributes		attrs should only be visible by the Admin role.	reserved
locality	Locality			reserved
ServerVersion	Version			reserved
build_tag	string			reserved
started_at	int64			reserved
locality_address	cockroach.roachpb.LocalityAddress	repeated	locality_address should only be visible by the Admin role.	reserved
cluster_name	string			reserved
sql_address	cockroach.util.UnresolvedAddr		The SQL address. If empty, indicates that the base address field is also used to accept SQL connections. sql_address should only be visible by the Admin role.	reserved

StoreStatus.MetricsEntry

Field	Type	Label	Description	Support status
key	string
value	double

NodeResponse.LatenciesEntry

Field	Type	Label	Description	Support status
key	int32
value	int64

NodeResponse.ActivityEntry

Field	Type	Label	Description	Support status
key	int32
value	NodeResponse.NetworkActivity

NodeResponse.NetworkActivity

Field	Type	Label	Description	Support status
latency	int64		in nanoseconds	reserved

RaftDebug

GET /_status/raft

RaftDebug requests internal details about Raft.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
range_ids	int64	repeated		reserved

Response Parameters

Field	Type	Label	Description	Support status
ranges	RaftDebugResponse.RangesEntry	repeated		reserved
errors	RaftRangeError	repeated		reserved

RaftDebugResponse.RangesEntry

Field	Type	Label	Description	Support status
key	int64
value	RaftRangeStatus

RaftRangeStatus

Field	Type	Label	Support status
range_id	int64		reserved
errors	RaftRangeError	repeated	reserved
nodes	RaftRangeNode	repeated	reserved

RaftRangeError

Field	Type	Label	Description	Support status
message	string			reserved

RaftRangeNode

Field	Type	Label	Description	Support status
node_id	int32			reserved
range	RangeInfo			reserved

RangeInfo

Field	Type	Label	Description	Support status
span	PrettySpan			reserved
raft_state	RaftState			reserved
rac_status	RACStatus			reserved
state	cockroach.kv.kvserver.storagepb.RangeInfo			reserved
source_node_id	int32			reserved
source_store_id	int32			reserved
error_message	string			reserved
lease_history	cockroach.roachpb.Lease	repeated		reserved
problems	RangeProblems			reserved
stats	RangeStatistics			reserved
lease_status	cockroach.kv.kvserver.storagepb.LeaseStatus			reserved
quiescent	bool			reserved
ticking	bool			reserved
read_latches	int64			reserved
write_latches	int64			reserved
locks	int64			reserved
locks_with_wait_queues	int64			reserved
lock_wait_queue_waiters	int64			reserved
top_k_locks_by_wait_queue_waiters	RangeInfo.LockInfo	repeated		reserved
locality	Locality			reserved
is_leaseholder	bool			reserved
lease_valid	bool		Next tag: 26	reserved

PrettySpan

Field	Type	Label	Description	Support status
start_key	string			reserved
end_key	string			reserved

RaftState

RaftState gives internal details about a Raft group's state. Closely mirrors the upstream definitions in github.com/etcd-io/raft.

Field	Type	Label	Description	Support status
replica_id	uint64			reserved
hard_state	raftpb.HardState			reserved
lead	uint64		Lead is part of Raft's HardState. However, it used to be part of SoftState, so we keep it here as a separate field for compatibility.	reserved
state	string		State is part of Raft's SoftState. It's not an enum because this is primarily for ui consumption and there are issues associated with them.	reserved
applied	uint64			reserved
progress	RaftState.ProgressEntry	repeated		reserved
lead_transferee	uint64			reserved
lead_support_until	cockroach.util.hlc.Timestamp			reserved

RaftState.ProgressEntry

Field	Type	Label	Description	Support status
key	uint64
value	RaftState.Progress

RaftState.Progress

Field	Type	Support status
match	uint64	reserved
next	uint64	reserved
state	string	reserved
paused	bool	reserved
pending_snapshot	uint64	reserved

RACStatus

RACStatus contains the status of the Replication Admission Control component of a range.

Field	Type	Label	Support status
next_raft_index	uint64		reserved
force_flush_index	uint64		reserved
streams	RACStatus.StreamsEntry	repeated	reserved

RACStatus.StreamsEntry

Field	Type	Label	Description	Support status
key	uint64
value	RACStatus.Stream

RACStatus.Stream

Field	Type	Label	Support status
index_to_send	uint64		reserved
next_raft_index_initial	uint64		reserved
force_flush_stop_index	uint64		reserved
eval_tokens_held	int64	repeated	reserved
send_tokens_held	int64	repeated	reserved

RangeProblems

RangeProblems describes issues reported by a range. For internal use only.

Field	Type	Description	Support status
unavailable	bool		reserved
leader_not_lease_holder	bool		reserved
no_raft_leader	bool		reserved
underreplicated	bool		reserved
overreplicated	bool		reserved
no_lease	bool		reserved
quiescent_equals_ticking	bool	Quiescent ranges do not tick by definition, but we track this in two different ways and suspect that they're getting out of sync. If the replica's quiescent flag doesn't agree with the store's list of replicas that are ticking, warn about it.	reserved
raft_log_too_large	bool	When the raft log is too large, it can be a symptom of other issues.	reserved
circuit_breaker_error	bool		reserved
paused_followers	bool		reserved
range_too_large	bool		reserved

RangeStatistics

RangeStatistics describes statistics reported by a range. For internal use only.

Field	Type	Description	Support status
queries_per_second	double	Queries per second (batch requests) served by this range per second, averaged over the last 30 minute period.	reserved
writes_per_second	double	Writes per second served is the number of keys written to this range per second, averaged over the last 30 minute period.	reserved
requests_per_second	double	Requests per second is the number of requests served by this range per second, averaged over the last 30 minute period.	reserved
reads_per_second	double	Reads per second served is the number of keys read from this range per second, averaged over the last 30 minute period.	reserved
write_bytes_per_second	double	Writes (bytes) per second is the number of bytes written to this range per second, averaged over the last 30 minute period.	reserved
read_bytes_per_second	double	Reads (bytes) per second is the number of bytes read from this range per second, averaged over the last 30 minute period.	reserved
cpu_time_per_second	double	CPU time (ns) per second is the cpu usage of this range per second, averaged over the last 30 minute period.	reserved

RangeInfo.LockInfo

Field	Type	Support status
pretty_key	string	reserved
key	bytes	reserved
held	bool	reserved
waiters	int64	reserved
waiting_readers	int64	reserved
waiting_writers	int64	reserved

Locality

Locality is an ordered set of key value Tiers that describe a node's location. The tier keys should be the same across all nodes.

Field	Type	Label	Description	Support status
tiers	Tier	repeated		reserved

Tier

Tier represents one level of the locality hierarchy.

Field	Type	Label	Description	Support status
key	string		Key is the name of tier and should match all other nodes.	reserved
value	string		Value is node specific value corresponding to the key.	reserved

RaftRangeError

Field	Type	Label	Description	Support status
message	string			reserved

Ranges

GET /_status/ranges/{node_id}

Ranges requests internal details about ranges on a given node.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string		node_id is a string so that "local" can be used to specify that no forwarding is necessary.	reserved
range_ids	int64	repeated		reserved
limit	int32		The pagination limit to use, if set. NB: Pagination is based on ascending RangeID.	reserved
offset	int32		The pagination offset to use, if set. NB: Pagination is based on ascending RangeID.	reserved
redact	bool		redact, if true, requests redaction of sensitive data away from the API response.	reserved

Response Parameters

Field	Type	Label	Description	Support status
ranges	RangeInfo	repeated		reserved
next	int32		The next pagination offset to use, if any results remain. A value of 0 indicates no more results. NB: Pagination is based on ascending RangeID.	reserved

RangeInfo

Field	Type	Label	Description	Support status
span	PrettySpan			reserved
raft_state	RaftState			reserved
rac_status	RACStatus			reserved
state	cockroach.kv.kvserver.storagepb.RangeInfo			reserved
source_node_id	int32			reserved
source_store_id	int32			reserved
error_message	string			reserved
lease_history	cockroach.roachpb.Lease	repeated		reserved
problems	RangeProblems			reserved
stats	RangeStatistics			reserved
lease_status	cockroach.kv.kvserver.storagepb.LeaseStatus			reserved
quiescent	bool			reserved
ticking	bool			reserved
read_latches	int64			reserved
write_latches	int64			reserved
locks	int64			reserved
locks_with_wait_queues	int64			reserved
lock_wait_queue_waiters	int64			reserved
top_k_locks_by_wait_queue_waiters	RangeInfo.LockInfo	repeated		reserved
locality	Locality			reserved
is_leaseholder	bool			reserved
lease_valid	bool		Next tag: 26	reserved

PrettySpan

Field	Type	Label	Description	Support status
start_key	string			reserved
end_key	string			reserved

RaftState

RaftState gives internal details about a Raft group's state. Closely mirrors the upstream definitions in github.com/etcd-io/raft.

Field	Type	Label	Description	Support status
replica_id	uint64			reserved
hard_state	raftpb.HardState			reserved
lead	uint64		Lead is part of Raft's HardState. However, it used to be part of SoftState, so we keep it here as a separate field for compatibility.	reserved
state	string		State is part of Raft's SoftState. It's not an enum because this is primarily for ui consumption and there are issues associated with them.	reserved
applied	uint64			reserved
progress	RaftState.ProgressEntry	repeated		reserved
lead_transferee	uint64			reserved
lead_support_until	cockroach.util.hlc.Timestamp			reserved

RaftState.ProgressEntry

Field	Type	Label	Description	Support status
key	uint64
value	RaftState.Progress

RaftState.Progress

Field	Type	Support status
match	uint64	reserved
next	uint64	reserved
state	string	reserved
paused	bool	reserved
pending_snapshot	uint64	reserved

RACStatus

RACStatus contains the status of the Replication Admission Control component of a range.

Field	Type	Label	Support status
next_raft_index	uint64		reserved
force_flush_index	uint64		reserved
streams	RACStatus.StreamsEntry	repeated	reserved

RACStatus.StreamsEntry

Field	Type	Label	Description	Support status
key	uint64
value	RACStatus.Stream

RACStatus.Stream

Field	Type	Label	Support status
index_to_send	uint64		reserved
next_raft_index_initial	uint64		reserved
force_flush_stop_index	uint64		reserved
eval_tokens_held	int64	repeated	reserved
send_tokens_held	int64	repeated	reserved

RangeProblems

RangeProblems describes issues reported by a range. For internal use only.

Field	Type	Description	Support status
unavailable	bool		reserved
leader_not_lease_holder	bool		reserved
no_raft_leader	bool		reserved
underreplicated	bool		reserved
overreplicated	bool		reserved
no_lease	bool		reserved
quiescent_equals_ticking	bool	Quiescent ranges do not tick by definition, but we track this in two different ways and suspect that they're getting out of sync. If the replica's quiescent flag doesn't agree with the store's list of replicas that are ticking, warn about it.	reserved
raft_log_too_large	bool	When the raft log is too large, it can be a symptom of other issues.	reserved
circuit_breaker_error	bool		reserved
paused_followers	bool		reserved
range_too_large	bool		reserved

RangeStatistics

RangeStatistics describes statistics reported by a range. For internal use only.

Field	Type	Description	Support status
queries_per_second	double	Queries per second (batch requests) served by this range per second, averaged over the last 30 minute period.	reserved
writes_per_second	double	Writes per second served is the number of keys written to this range per second, averaged over the last 30 minute period.	reserved
requests_per_second	double	Requests per second is the number of requests served by this range per second, averaged over the last 30 minute period.	reserved
reads_per_second	double	Reads per second served is the number of keys read from this range per second, averaged over the last 30 minute period.	reserved
write_bytes_per_second	double	Writes (bytes) per second is the number of bytes written to this range per second, averaged over the last 30 minute period.	reserved
read_bytes_per_second	double	Reads (bytes) per second is the number of bytes read from this range per second, averaged over the last 30 minute period.	reserved
cpu_time_per_second	double	CPU time (ns) per second is the cpu usage of this range per second, averaged over the last 30 minute period.	reserved

RangeInfo.LockInfo

Field	Type	Support status
pretty_key	string	reserved
key	bytes	reserved
held	bool	reserved
waiters	int64	reserved
waiting_readers	int64	reserved
waiting_writers	int64	reserved

Locality

Locality is an ordered set of key value Tiers that describe a node's location. The tier keys should be the same across all nodes.

Field	Type	Label	Description	Support status
tiers	Tier	repeated		reserved

Tier

Tier represents one level of the locality hierarchy.

Field	Type	Label	Description	Support status
key	string		Key is the name of tier and should match all other nodes.	reserved
value	string		Value is node specific value corresponding to the key.	reserved

TenantServiceStatus

GET /_status/tenant_service_status

TenantServiceStatus returns the current service and data state of the given tenant as known to the server orchestrator, which may differ from the database state.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string			reserved
tenant_id	uint64			reserved

Response Parameters

Field	Type	Label	Description	Support status
status_by_node_id	TenantServiceStatusResponse.StatusByNodeIdEntry	repeated		reserved
errors_by_node_id	TenantServiceStatusResponse.ErrorsByNodeIdEntry	repeated		reserved

TenantServiceStatusResponse.StatusByNodeIdEntry

Field	Type	Label	Description	Support status
key	int32
value	cockroach.multitenant.SQLInfo

TenantServiceStatusResponse.ErrorsByNodeIdEntry

Field	Type	Label	Description	Support status
key	int32
value	string

TenantRanges

GET /_status/tenant_ranges

TenantRanges requests internal details about all range replicas within the tenant's keyspace at the time the request is processed.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
limit	int32		The pagination limit. This limit will be applied to each node, meaning that if a range is replicated 3 times, 3*limit elements will be returned. NB: Pagination here is based on ascending RangeID.	reserved
offset	int32		The pagination offset. NB: Pagination here is based on ascending RangeID.	reserved

Response Parameters

Field	Type	Label	Description	Support status
ranges_by_locality	TenantRangesResponse.RangesByLocalityEntry	repeated	ranges_by_locality maps each range replica to its specified availability zone, as defined within the replica's locality metadata (default key `az`). Replicas without the default available zone key set will fall under the `locality-unset` key.	reserved
next	int32		The next offset, if pagination was used. NB: Pagination here is based on ascending RangeID.	reserved

TenantRangesResponse.RangesByLocalityEntry

Field	Type	Label	Description	Support status
key	string
value	TenantRangesResponse.TenantRangeList

TenantRangesResponse.TenantRangeList

Field	Type	Label	Description	Support status
ranges	TenantRangeInfo	repeated		reserved

TenantRangeInfo

TenantRangeInfo provides metadata about a specific range replica, where concepts not considered to be relevant within the tenant abstraction (e.g. NodeIDs) are omitted. Instead, Locality information is used to distinguish replicas.

Field	Type	Label	Description	Support status
range_id	int64		The ID of the Range.	reserved
span	PrettySpan		The pretty-printed key span of the range.	reserved
locality	Locality		Any locality information associated with this specific replica.	reserved
is_leaseholder	bool		Whether the range's specific replica is a leaseholder.	reserved
lease_valid	bool		Whether the range's specific replica holds a valid lease.	reserved
range_stats	RangeStatistics		Statistics about the range replica, e.g. QPS, WPS.	reserved
mvcc_stats	cockroach.storage.enginepb.MVCCStats		MVCC stats about the range replica, e.g. live_bytes.	reserved
read_latches	int64		Read count as reported by the range replica's spanlatch.Manager.	reserved
write_latches	int64		Write count as reported by the range replica's spanlatch.Manager.	reserved
locks	int64		The number of locks as reported by the range replica's lockTable.	reserved
locks_with_wait_queues	int64		The number of locks with non-empty wait-queues as reported by the range replica's lockTable	reserved
lock_wait_queue_waiters	int64		The aggregate number of waiters in wait-queues across all locks as reported by the range replica's lockTable	reserved
top_k_locks_by_wait_queue_waiters	TenantRangeInfo.LockInfo	repeated	The top-k locks with the most waiters (readers + writers) in their wait-queue, ordered in descending order.	reserved

PrettySpan

Field	Type	Label	Description	Support status
start_key	string			reserved
end_key	string			reserved

Locality

Locality is an ordered set of key value Tiers that describe a node's location. The tier keys should be the same across all nodes.

Field	Type	Label	Description	Support status
tiers	Tier	repeated		reserved

Tier

Tier represents one level of the locality hierarchy.

Field	Type	Label	Description	Support status
key	string		Key is the name of tier and should match all other nodes.	reserved
value	string		Value is node specific value corresponding to the key.	reserved

RangeStatistics

RangeStatistics describes statistics reported by a range. For internal use only.

Field	Type	Description	Support status
queries_per_second	double	Queries per second (batch requests) served by this range per second, averaged over the last 30 minute period.	reserved
writes_per_second	double	Writes per second served is the number of keys written to this range per second, averaged over the last 30 minute period.	reserved
requests_per_second	double	Requests per second is the number of requests served by this range per second, averaged over the last 30 minute period.	reserved
reads_per_second	double	Reads per second served is the number of keys read from this range per second, averaged over the last 30 minute period.	reserved
write_bytes_per_second	double	Writes (bytes) per second is the number of bytes written to this range per second, averaged over the last 30 minute period.	reserved
read_bytes_per_second	double	Reads (bytes) per second is the number of bytes read from this range per second, averaged over the last 30 minute period.	reserved
cpu_time_per_second	double	CPU time (ns) per second is the cpu usage of this range per second, averaged over the last 30 minute period.	reserved

TenantRangeInfo.LockInfo

LockInfo provides metadata about the state of a single lock in the range replica's lockTable.

Field	Type	Description	Support status
pretty_key	string	The lock's key in pretty format.	reserved
key	bytes	The lock's key.	reserved
held	bool	Is the lock actively held by a transaction, or just a reservation?	reserved
waiters	int64	The number of waiters in the lock's wait queue.	reserved
waiting_readers	int64	The number of waiting readers in the lock's wait queue.	reserved
waiting_writers	int64	The number of waiting writers in the lock's wait queue.	reserved

Gossip

GET /_status/gossip/{node_id}

Gossip retrieves gossip-level details about a given node.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string		node_id is a string so that "local" can be used to specify that no forwarding is necessary.	reserved
redact	bool		redact, if true, requests redaction of sensitive data away from the API response.	reserved

Response Parameters

EngineStats

GET /_status/enginestats/{node_id}

EngineStats retrieves statistics about a storage engine.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string		node_id is a string so that "local" can be used to specify that no forwarding is necessary.	reserved

Response Parameters

Field	Type	Label	Description	Support status
stats_by_store_id	EngineStatsResponse.StatsByStoreIdEntry	repeated	maps store IDs to pretty-printed stats about the store's LSM.	reserved

EngineStatsResponse.StatsByStoreIdEntry

Field	Type	Label	Description	Support status
key	int32
value	string

Allocator

GET /_status/allocator/node/{node_id}

Allocator retrieves statistics about the replica allocator.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string			reserved
range_ids	int64	repeated		reserved

Response Parameters

Field	Type	Label	Description	Support status
dry_runs	AllocatorDryRun	repeated		reserved

AllocatorDryRun

Field	Type	Label	Description	Support status
range_id	int64			reserved
events	TraceEvent	repeated		reserved

TraceEvent

Field	Type	Label	Description	Support status
time	google.protobuf.Timestamp			reserved
message	string			reserved

AllocatorRange

GET /_status/allocator/range/{range_id}

AllocatorRange retrieves statistics about the replica allocator given a specific range.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
range_id	int64			reserved

Response Parameters

Field	Type	Label	Description	Support status
node_id	int64		The NodeID of the store whose dry run is returned. Only the leaseholder for a given range will do an allocator dry run for it.	reserved
dry_run	AllocatorDryRun			reserved

AllocatorDryRun

Field	Type	Label	Description	Support status
range_id	int64			reserved
events	TraceEvent	repeated		reserved

TraceEvent

Field	Type	Label	Description	Support status
time	google.protobuf.Timestamp			reserved
message	string			reserved

ListSessions

GET /_status/sessions

ListSessions retrieves the SQL sessions across the entire cluster.

Support status: reserved

Request Parameters

Request object for ListSessions and ListLocalSessions.

Field	Type	Description	Support status
username	string	Username of the user making this request. The caller is responsible to normalize the username (= case fold and perform unicode NFC normalization).	reserved
exclude_closed_sessions	bool	Boolean to exclude closed sessions; if unspecified, defaults to false and closed sessions are included in the response.	reserved
include_internal	bool	Boolean to surface internal sessions in the response. Note that this param currently serves as an override for the cluster setting sql.stats.response.show_internal.enabled until #87200 is addressed, and setting this param to false is equivalent to setting the value to sql.stats.response.show_internal.enabled	reserved

Response Parameters

Response object for ListSessions and ListLocalSessions.

Field	Type	Label	Description	Support status
sessions	Session	repeated	A list of sessions on this node or cluster.	reserved
errors	ListSessionsError	repeated	Any errors that occurred during fan-out calls to other nodes.	reserved
internal_app_name_prefix	string		If set and non-empty, indicates the prefix to application_name used for statements/queries issued internally by CockroachDB.	reserved

Session

Session represents one SQL session.

Field	Type	Label	Description	Support status
node_id	int32		ID of node where this session exists.	reserved
username	string		Username of the user for this session.	reserved
client_address	string		Connected client's IP address and port.	reserved
application_name	string		Application name specified by the client.	reserved
active_queries	ActiveQuery	repeated	Queries in progress on this session.	reserved
start	google.protobuf.Timestamp		Timestamp of session's start.	reserved
last_active_query	string		SQL string of the last query executed on this session.	reserved
id	bytes		ID of the session (uint128 represented as raw bytes).	reserved
alloc_bytes	int64		Number of currently allocated bytes in the session memory monitor.	reserved
max_alloc_bytes	int64		High water mark of allocated bytes in the session memory monitor.	reserved
active_txn	TxnInfo		Information about the txn in progress on this session. Nil if the session doesn't currently have a transaction.	reserved
last_active_query_no_constants	string		The SQL statement fingerprint of the last query executed on this session, compatible with StatementStatisticsKey.	reserved
status	Session.Status		The session's status.	reserved
end	google.protobuf.Timestamp		Timestamp of session's end.	reserved
num_txns_executed	int32		Count of the number of transactions that have been opened on this session. This count includes transactions that are in progress.	reserved
txn_fingerprint_ids	uint64	repeated	List of transaction fingerprint IDs in this session.	reserved
total_active_time	google.protobuf.Duration		The session's total active time.	reserved
pg_backend_pid	uint32		The numerical ID attached to the session which is used to mimic a Postgres backend PID for compatibility with the query cancellation protocol. Unlike in Postgres, this value does not correspond to a real process ID.	reserved
trace_id	uint64		The ID of the session's active trace. It will be 0 if tracing is off.	reserved
goroutine_id	int64		The ID of the session's goroutine.	reserved
authentication_method	string			reserved
default_isolation_level	string		The session's default transaction isolation level.	reserved

ActiveQuery

ActiveQuery represents a query in flight on some Session.

Field	Type	Label	Description	Support status
id	string		ID of the query (uint128 presented as a hexadecimal string).	reserved
txn_id	bytes		The UUID of the transaction this query is running in.	reserved
sql	string		SQL query string specified by the user.	reserved
start	google.protobuf.Timestamp		Start timestamp of this query.	reserved
is_distributed	bool		True if this query is distributed.	reserved
phase	ActiveQuery.Phase		phase stores the current phase of execution for this query.	reserved
progress	float		progress is an estimate of the fraction of this query that has been processed.	reserved
sql_no_constants	string		The SQL statement fingerprint, compatible with StatementStatisticsKey.	reserved
sql_summary	string		A summarized version of the sql query.	reserved
is_full_scan	bool		True if the query contains a full table or index scan. Note that this field is only valid if the query is in the EXECUTING phase.	reserved
elapsed_time	google.protobuf.Duration		Time elapsed since this query started execution.	reserved
plan_gist	string		The compressed plan that can be converted back into the statement's logical plan. Empty if the statement is in the PREPARING state.	reserved
placeholders	string	repeated	The placeholders if any.	reserved
database	string		The database the statement was executed on.	reserved
isolation_level	string		The isolation level the query was run in.	reserved

TxnInfo

TxnInfo represents an in flight user transaction on some Session.

Field	Type	Description	Support status
id	bytes		reserved
start	google.protobuf.Timestamp	The start timestamp of the transaction.	reserved
txn_description	string	txn_description is a text description of the underlying kv.Txn, intended for troubleshooting purposes.	reserved
num_statements_executed	int32	num_statements_executed is the number of statements that were executed so far on this transaction.	reserved
num_retries	int32	num_retries is the number of times that this transaction was retried.	reserved
num_auto_retries	int32	num_retries is the number of times that this transaction was automatically retried by the SQL executor.	reserved
deadline	google.protobuf.Timestamp	The deadline by which the transaction must be committed.	reserved
implicit	bool	implicit is true if this transaction was an implicit SQL transaction.	reserved
alloc_bytes	int64	Number of currently allocated bytes in the txn memory monitor.	reserved
max_alloc_bytes	int64	High water mark of allocated bytes in the txn memory monitor.	reserved
read_only	bool		reserved
is_historical	bool		reserved
priority	string		reserved
quality_of_service	string		reserved
last_auto_retry_reason	string	Error message describing the cause for the txn's last automatic retry.	reserved
elapsed_time	google.protobuf.Duration	Time elapsed since this transaction started execution.	reserved
isolation_level	string	The isolation level of the transaction.	reserved

ListSessionsError

An error wrapper object for ListSessionsResponse.

Field	Type	Label	Description	Support status
node_id	int32		ID of node that was being contacted when this error occurred	reserved
message	string		Error message.	reserved

ListLocalSessions

GET /_status/local_sessions

ListLocalSessions retrieves the SQL sessions on this node.

Support status: reserved

Request Parameters

Request object for ListSessions and ListLocalSessions.

Field	Type	Description	Support status
username	string	Username of the user making this request. The caller is responsible to normalize the username (= case fold and perform unicode NFC normalization).	reserved
exclude_closed_sessions	bool	Boolean to exclude closed sessions; if unspecified, defaults to false and closed sessions are included in the response.	reserved
include_internal	bool	Boolean to surface internal sessions in the response. Note that this param currently serves as an override for the cluster setting sql.stats.response.show_internal.enabled until #87200 is addressed, and setting this param to false is equivalent to setting the value to sql.stats.response.show_internal.enabled	reserved

Response Parameters

Response object for ListSessions and ListLocalSessions.

Field	Type	Label	Description	Support status
sessions	Session	repeated	A list of sessions on this node or cluster.	reserved
errors	ListSessionsError	repeated	Any errors that occurred during fan-out calls to other nodes.	reserved
internal_app_name_prefix	string		If set and non-empty, indicates the prefix to application_name used for statements/queries issued internally by CockroachDB.	reserved

Session

Session represents one SQL session.

Field	Type	Label	Description	Support status
node_id	int32		ID of node where this session exists.	reserved
username	string		Username of the user for this session.	reserved
client_address	string		Connected client's IP address and port.	reserved
application_name	string		Application name specified by the client.	reserved
active_queries	ActiveQuery	repeated	Queries in progress on this session.	reserved
start	google.protobuf.Timestamp		Timestamp of session's start.	reserved
last_active_query	string		SQL string of the last query executed on this session.	reserved
id	bytes		ID of the session (uint128 represented as raw bytes).	reserved
alloc_bytes	int64		Number of currently allocated bytes in the session memory monitor.	reserved
max_alloc_bytes	int64		High water mark of allocated bytes in the session memory monitor.	reserved
active_txn	TxnInfo		Information about the txn in progress on this session. Nil if the session doesn't currently have a transaction.	reserved
last_active_query_no_constants	string		The SQL statement fingerprint of the last query executed on this session, compatible with StatementStatisticsKey.	reserved
status	Session.Status		The session's status.	reserved
end	google.protobuf.Timestamp		Timestamp of session's end.	reserved
num_txns_executed	int32		Count of the number of transactions that have been opened on this session. This count includes transactions that are in progress.	reserved
txn_fingerprint_ids	uint64	repeated	List of transaction fingerprint IDs in this session.	reserved
total_active_time	google.protobuf.Duration		The session's total active time.	reserved
pg_backend_pid	uint32		The numerical ID attached to the session which is used to mimic a Postgres backend PID for compatibility with the query cancellation protocol. Unlike in Postgres, this value does not correspond to a real process ID.	reserved
trace_id	uint64		The ID of the session's active trace. It will be 0 if tracing is off.	reserved
goroutine_id	int64		The ID of the session's goroutine.	reserved
authentication_method	string			reserved
default_isolation_level	string		The session's default transaction isolation level.	reserved

ActiveQuery

ActiveQuery represents a query in flight on some Session.

Field	Type	Label	Description	Support status
id	string		ID of the query (uint128 presented as a hexadecimal string).	reserved
txn_id	bytes		The UUID of the transaction this query is running in.	reserved
sql	string		SQL query string specified by the user.	reserved
start	google.protobuf.Timestamp		Start timestamp of this query.	reserved
is_distributed	bool		True if this query is distributed.	reserved
phase	ActiveQuery.Phase		phase stores the current phase of execution for this query.	reserved
progress	float		progress is an estimate of the fraction of this query that has been processed.	reserved
sql_no_constants	string		The SQL statement fingerprint, compatible with StatementStatisticsKey.	reserved
sql_summary	string		A summarized version of the sql query.	reserved
is_full_scan	bool		True if the query contains a full table or index scan. Note that this field is only valid if the query is in the EXECUTING phase.	reserved
elapsed_time	google.protobuf.Duration		Time elapsed since this query started execution.	reserved
plan_gist	string		The compressed plan that can be converted back into the statement's logical plan. Empty if the statement is in the PREPARING state.	reserved
placeholders	string	repeated	The placeholders if any.	reserved
database	string		The database the statement was executed on.	reserved
isolation_level	string		The isolation level the query was run in.	reserved

TxnInfo

TxnInfo represents an in flight user transaction on some Session.

Field	Type	Description	Support status
id	bytes		reserved
start	google.protobuf.Timestamp	The start timestamp of the transaction.	reserved
txn_description	string	txn_description is a text description of the underlying kv.Txn, intended for troubleshooting purposes.	reserved
num_statements_executed	int32	num_statements_executed is the number of statements that were executed so far on this transaction.	reserved
num_retries	int32	num_retries is the number of times that this transaction was retried.	reserved
num_auto_retries	int32	num_retries is the number of times that this transaction was automatically retried by the SQL executor.	reserved
deadline	google.protobuf.Timestamp	The deadline by which the transaction must be committed.	reserved
implicit	bool	implicit is true if this transaction was an implicit SQL transaction.	reserved
alloc_bytes	int64	Number of currently allocated bytes in the txn memory monitor.	reserved
max_alloc_bytes	int64	High water mark of allocated bytes in the txn memory monitor.	reserved
read_only	bool		reserved
is_historical	bool		reserved
priority	string		reserved
quality_of_service	string		reserved
last_auto_retry_reason	string	Error message describing the cause for the txn's last automatic retry.	reserved
elapsed_time	google.protobuf.Duration	Time elapsed since this transaction started execution.	reserved
isolation_level	string	The isolation level of the transaction.	reserved

ListSessionsError

An error wrapper object for ListSessionsResponse.

Field	Type	Label	Description	Support status
node_id	int32		ID of node that was being contacted when this error occurred	reserved
message	string		Error message.	reserved

CancelQuery

POST /_status/cancel_query/{node_id}

CancelQuery cancels a SQL query given its ID.

Support status: reserved

Request Parameters

Request object for issuing a query cancel request.

Field	Type	Label	Description	Support status
node_id	string		ID of gateway node for the query to be canceled.

TODO(itsbilal): use [(gogoproto.customname) = "NodeID"] below. Need to figure out how to teach grpc-gateway about custom names.

Response Parameters

Response returned by target query's gateway node.

Field	Type	Label	Description	Support status
canceled	bool		Whether the cancellation request succeeded and the query was canceled.	reserved
error	string		Error message (accompanied with canceled = false).	reserved

CancelQueryByKey

CancelQueryByKey cancels a SQL query given its pgwire BackendKeyData. It is invoked through the pgwire protocol, so it's not exposed as an HTTP endpoint.

Support status: reserved

Request Parameters

Request object for issuing a pgwire query cancel request.

Field	Type	Label	Description	Support status
sql_instance_id	int32		The SQLInstanceID of the gateway node for the query to be canceled.	reserved
cancel_query_key	uint64		The key that was generated during session initialization as part of the pgwire protocol.	reserved

Response Parameters

Response returned by target query's gateway node for a pgwire cancel request.

Field	Type	Label	Description	Support status
canceled	bool		Whether the cancellation request succeeded and the query was canceled.	reserved
error	string		Error message (accompanied with canceled = false).	reserved

ListContentionEvents

GET /_status/contention_events

ListContentionEvents retrieves the contention events across the entire cluster.

For SQL keys the following orderings are maintained:

on the highest level, all IndexContentionEvents objects are ordered according to their importance (as defined by the number of contention events within each object).
on the middle level, all SingleKeyContention objects are ordered by their keys lexicographically.
on the lowest level, all SingleTxnContention objects are ordered by the number of times that transaction was observed to contend with other transactions.

For non-SQL keys the following orderings are maintained:

on the top level, all SingleNonSQLKeyContention objects are ordered by their keys lexicographically.
on the bottom level, all SingleTxnContention objects are ordered by the number of times that transaction was observed to contend with other transactions.

Support status: reserved

Request Parameters

Request object for ListContentionEvents and ListLocalContentionEvents.

Response Parameters

Response object for ListContentionEvents and ListLocalContentionEvents.

Field	Type	Label	Description	Support status
events	cockroach.sql.contentionpb.SerializedRegistry		All available contention information on this node or cluster.	reserved
errors	ListActivityError	repeated	Any errors that occurred during fan-out calls to other nodes.	reserved

ListActivityError

An error wrapper object for ListContentionEventsResponse and ListDistSQLFlowsResponse. Similar to the Statements endpoint, when implemented on a tenant, the node_id field refers to the instanceIDs that identify individual tenant pods.

Field	Type	Label	Description	Support status
node_id	int32		ID of node that was being contacted when this error occurred.	reserved
message	string		Error message.	reserved

ListLocalContentionEvents

GET /_status/local_contention_events

ListLocalContentionEvents retrieves the contention events on this node.

For SQL keys the following orderings are maintained:

on the highest level, all IndexContentionEvents objects are ordered according to their importance (as defined by the number of contention events within each object).
on the middle level, all SingleKeyContention objects are ordered by their keys lexicographically.
on the lowest level, all SingleTxnContention objects are ordered by the number of times that transaction was observed to contend with other transactions.

For non-SQL keys the following orderings are maintained:

on the top level, all SingleNonSQLKeyContention objects are ordered by their keys lexicographically.
on the bottom level, all SingleTxnContention objects are ordered by the number of times that transaction was observed to contend with other transactions.

Support status: reserved

Request Parameters

Request object for ListContentionEvents and ListLocalContentionEvents.

Response Parameters

Response object for ListContentionEvents and ListLocalContentionEvents.

Field	Type	Label	Description	Support status
events	cockroach.sql.contentionpb.SerializedRegistry		All available contention information on this node or cluster.	reserved
errors	ListActivityError	repeated	Any errors that occurred during fan-out calls to other nodes.	reserved

ListActivityError

Field	Type	Label	Description	Support status
node_id	int32		ID of node that was being contacted when this error occurred.	reserved
message	string		Error message.	reserved

ListDistSQLFlows

GET /_status/distsql_flows

ListDistSQLFlows retrieves all of the remote flows of the DistSQL execution that are currently running or queued on any node in the cluster. The local flows (those that are running on the same node as the query originated on) are not included.

Flows are ordered lexicographically by the flow ID.

Support status: reserved

Request Parameters

Request object for ListDistSQLFlows and ListLocalDistSQLFlows.

Response Parameters

Response object for ListDistSQLFlows and ListLocalDistSQLFlows.

Field	Type	Label	Description	Support status
flows	DistSQLRemoteFlows	repeated	Flows are ordered by FlowID lexicographically and do not contain duplicates.	reserved
errors	ListActivityError	repeated	Any errors that occurred during fan-out calls to other nodes.	reserved

DistSQLRemoteFlows

DistSQLRemoteFlows describes all DistSQL remote flows that are part of the same physical plan. The gateway node that initiated the execution of the plan isn't included.

Field	Type	Label	Description	Support status
flow_id	bytes		FlowID is the unique identifier of the physical plan shared by all remote flows.	reserved
infos	DistSQLRemoteFlows.Info	repeated	Infos contains the information about all remote flows that are part of this DistSQL physical plan and that haven't finished yet.

The slice doesn't contain duplicate NodeIDs and is sorted by NodeID in ASC order. | reserved |

DistSQLRemoteFlows.Info

Info contains an information about a single DistSQL remote flow.

Field	Type	Description	Support status
node_id	int32	NodeID is the node on which this remote flow is either running or queued.	reserved
timestamp	google.protobuf.Timestamp	Timestamp must be in the UTC timezone.	reserved
stmt	string	Stmt is the SQL statement for which this flow is executing.	reserved

ListActivityError

Field	Type	Label	Description	Support status
node_id	int32		ID of node that was being contacted when this error occurred.	reserved
message	string		Error message.	reserved

ListLocalDistSQLFlows

GET /_status/local_distsql_flows

ListLocalDistSQLFlows retrieves all of the remote flows of the DistSQL execution that are currently running or queued on this node in the cluster. Queries that originated on this node are not be included.

Flows are ordered lexicographically by the flow ID.

Support status: reserved

Request Parameters

Request object for ListDistSQLFlows and ListLocalDistSQLFlows.

Response Parameters

Response object for ListDistSQLFlows and ListLocalDistSQLFlows.

Field	Type	Label	Description	Support status
flows	DistSQLRemoteFlows	repeated	Flows are ordered by FlowID lexicographically and do not contain duplicates.	reserved
errors	ListActivityError	repeated	Any errors that occurred during fan-out calls to other nodes.	reserved

DistSQLRemoteFlows

DistSQLRemoteFlows describes all DistSQL remote flows that are part of the same physical plan. The gateway node that initiated the execution of the plan isn't included.

Field	Type	Label	Description	Support status
flow_id	bytes		FlowID is the unique identifier of the physical plan shared by all remote flows.	reserved
infos	DistSQLRemoteFlows.Info	repeated	Infos contains the information about all remote flows that are part of this DistSQL physical plan and that haven't finished yet.

The slice doesn't contain duplicate NodeIDs and is sorted by NodeID in ASC order. | reserved |

DistSQLRemoteFlows.Info

Info contains an information about a single DistSQL remote flow.

Field	Type	Description	Support status
node_id	int32	NodeID is the node on which this remote flow is either running or queued.	reserved
timestamp	google.protobuf.Timestamp	Timestamp must be in the UTC timezone.	reserved
stmt	string	Stmt is the SQL statement for which this flow is executing.	reserved

ListActivityError

Field	Type	Label	Description	Support status
node_id	int32		ID of node that was being contacted when this error occurred.	reserved
message	string		Error message.	reserved

CancelSession

POST /_status/cancel_session/{node_id}

CancelSessions forcefully terminates a SQL session given its ID.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string		TODO(abhimadan): use [(gogoproto.customname) = "NodeID"] below. Need to figure out how to teach grpc-gateway about custom names.

Response Parameters

Field	Type	Label	Description	Support status
canceled	bool			reserved
error	string			reserved

SpanStats

POST /_status/span

SpanStats accepts a key span and node ID, and returns a set of stats summed from all ranges on the stores on that node which contain keys in that span. This is designed to compute stats specific to a SQL table: it will be called with the highest/lowest key for a SQL table, and return information about the resources on a node used by that table.

Support status: reserved

Request Parameters

Response Parameters

CriticalNodes

POST /_status/critical_nodes

CriticalNodes retrieves nodes that are considered critical. A critical node is one whose unexpected termination could result in data loss. A node is considered critical if any of its replicas are unavailable or under-replicated. The response includes a list of node descriptors that are considered critical, and the corresponding SpanConfigConformanceReport that includes details of non-conforming ranges contributing to the criticality.

Support status: reserved

Request Parameters

Response Parameters

Field	Type	Label	Description	Support status
critical_nodes	cockroach.roachpb.NodeDescriptor	repeated		reserved
report	cockroach.roachpb.SpanConfigConformanceReport			reserved

Stacks

GET /_status/stacks/{node_id}

Stacks retrieves the stack traces of all goroutines on a given node.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string		node_id is a string so that "local" can be used to specify that no forwarding is necessary. node_id translates to a KV node ID on a storage server and SQL instance ID on a SQL only server.	reserved
type	StacksType			reserved

Response Parameters

Field	Type	Label	Description	Support status
data	bytes			reserved

Profile

GET /_status/profile/{node_id}

Profile retrieves a CPU profile on a given node.

Support status: reserved

Request Parameters

Field	Type	Description	Support status
node_id	string	node_id is a string so that "local" or "all" can be used to specify that no forwarding is necessary. node_id translates to a KV node ID on a storage server and SQL instance ID on a SQL only server.	reserved
type	ProfileRequest.Type	The type of profile to retrieve.	reserved
seconds	int32	applies only to Type=CPU, defaults to 30	reserved
labels	bool	Labels can be specified for Type=CPU or Type=GOROUTINE.

If true for CPU profiles, we request a CPU profile with pprof labels.
If true for GOROUTINE profiles, we request an aggregated goroutine profile with debug=1. | reserved | | label_filter | string | | LabelFilter only applies to Type=GOROUTINE. Only goroutines with a pprof label matching the filter will be returned. | reserved | | sender_server_version | cockroach.roachpb.Version | | SenderServerVersion is the server version of the node sending the Profile request. If this field is set then the node processing the request will only collect the profile if its server version is equal to the sender's server version.

Currently, this is only used when collecting profiles that will be merged using pprof.Merge as all the samples must be from the same binary version. | reserved |

Response Parameters

Field	Type	Label	Description	Support status
data	bytes			reserved

Metrics

GET /_status/metrics/{node_id}

Metrics retrieves the node metrics for a given node.

Note: this is a “reserved” API and should not be relied upon to build external tools. No guarantee is made about its availability and stability in external uses.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string		node_id is a string so that "local" can be used to specify that no forwarding is necessary.	reserved

Response Parameters

Field	Type	Label	Description	Support status
data	bytes			reserved

GetFiles

GET /_status/files/{node_id}

GetFiles retrieves heap or goroutine dump files from a given node.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string		node_id is a string so that "local" can be used to specify that no forwarding is necessary. node_id translates to a KV node ID on a storage server and SQL instance ID on a SQL only server.	reserved
list_only	bool		If list_only is true then the contents of the files will not be populated in the response. Only filenames and sizes will be returned.	reserved
type	FileType			reserved
patterns	string	repeated	Each pattern given is matched with Files of the above type in the node using filepath.Glob(). The patterns only match to filenames and so path separators cannot be used. Example: * will match all files of requested type.	reserved

Response Parameters

Field	Type	Label	Description	Support status
files	File	repeated		reserved

File

Field	Type	Description	Support status
name	string		reserved
file_size	int64		reserved
contents	bytes	Contents may not be populated if only a list of Files are requested.	reserved

LogFilesList

GET /_status/logfiles/{node_id}

LogFilesList retrieves a list of log files on a given node.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string		node_id is a string so that "local" can be used to specify that no forwarding is necessary.	reserved

Response Parameters

Field	Type	Label	Description	Support status
files	cockroach.util.log.FileInfo	repeated	files is the list of log files under this node's configured logging directories. Note that the response does not contain detail about which directory contains which file. The location of each file is known to the server based on its name and the logging configuration.	reserved

LogFile

GET /_status/logfiles/{node_id}/{file}

LogFile retrieves a given log file.

Support status: reserved

Request Parameters

Field	Type	Description	Support status
node_id	string	node_id is a string so that "local" can be used to specify that no forwarding is necessary.	reserved
file	string	file is the name of the log file to retrieve. Note that it must not be prefixed by a directory name. The full path to the file is computed by the server based on the base name and the logging configuration.	reserved
redact	bool	redact, if true, requests redaction of sensitive data away from the retrieved log entries. Only admin users can send a request with redact = false.	reserved

Response Parameters

Field	Type	Label	Description	Support status
entries	cockroach.util.log.Entry	repeated		reserved
parse_errors	string	repeated	parse_errors contains list of errors that occurred during retrieving individual log entries that don't prevent to return at least partial response.	reserved

Logs

GET /_status/logs/{node_id}

Logs retrieves individual log entries.

Support status: reserved

Request Parameters

Field	Type	Description	Support status
node_id	string	node_id is a string so that "local" can be used to specify that no forwarding is necessary.	reserved
level	string		reserved
start_time	string		reserved
end_time	string		reserved
max	string		reserved
pattern	string		reserved
redact	bool	redact, if true, requests redaction of sensitive data away from the retrieved log entries. Only admin users can send a request with redact = false.	reserved

Response Parameters

Field	Type	Label	Description	Support status
entries	cockroach.util.log.Entry	repeated		reserved
parse_errors	string	repeated	parse_errors contains list of errors that occurred during retrieving individual log entries that don't prevent to return at least partial response.	reserved

ProblemRanges

GET /_status/problemranges

ProblemRanges retrieves the list of “problem ranges”.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string		If left empty, problem ranges for all nodes/stores will be returned.	reserved

Response Parameters

Field	Type	Label	Description	Support status
node_id	int32		NodeID is the node that submitted all the requests.	reserved
problems_by_node_id	ProblemRangesResponse.ProblemsByNodeIdEntry	repeated		reserved

ProblemRangesResponse.ProblemsByNodeIdEntry

Field	Type	Label	Description	Support status
key	int32
value	ProblemRangesResponse.NodeProblems

ProblemRangesResponse.NodeProblems

Field	Type	Label	Support status
error_message	string		reserved
unavailable_range_ids	int64	repeated	reserved
raft_leader_not_lease_holder_range_ids	int64	repeated	reserved
no_raft_leader_range_ids	int64	repeated	reserved
no_lease_range_ids	int64	repeated	reserved
underreplicated_range_ids	int64	repeated	reserved
overreplicated_range_ids	int64	repeated	reserved
quiescent_equals_ticking_range_ids	int64	repeated	reserved
raft_log_too_large_range_ids	int64	repeated	reserved
circuit_breaker_error_range_ids	int64	repeated	reserved
paused_replica_ids	int64	repeated	reserved
too_large_range_ids	int64	repeated	reserved

DownloadSpan

GET /_status/downloadspans

Support status: reserved

Request Parameters

Field	Type	Label	Support status
node_id	string		reserved
spans	cockroach.roachpb.Span	repeated	reserved
via_backing_file_download	bool		reserved

Response Parameters

Field	Type	Label	Description	Support status
errors	DownloadSpanResponse.ErrorsEntry	repeated		reserved

DownloadSpanResponse.ErrorsEntry

Field	Type	Label	Description	Support status
key	int32
value	cockroach.errorspb.EncodedError

HotRangesV2

POST /_status/v2/hotranges

Support status: reserved

Request Parameters

HotRangesRequest queries one or more cluster nodes for a list of ranges currently considered “hot” by the node(s).

Field	Type	Label	Description	Support status
node_id	string		NodeID indicates which node to query for a hot range report. It is possible to populate any node ID; if the node receiving the request is not the target node, it will forward the request to the target node.

Response Parameters

HotRangesResponseV2 is a response payload returned by HotRangesV2 service.

Field	Type	Label	Description	Support status
ranges	HotRangesResponseV2.HotRange	repeated	Ranges contain list of hot ranges info that has highest number of QPS.	reserved
errors_by_node_id	HotRangesResponseV2.ErrorsByNodeIdEntry	repeated	errors contains any errors that occurred during fan-out calls to other nodes.	reserved
next_page_token	string		NextPageToken represents next pagination token to request next slice of data.	reserved

HotRangesResponseV2.HotRange

HotRange message describes a single hot range, ie its QPS, node ID it belongs to, etc.

Field	Type	Label	Description	Support status
range_id	int32		range_id indicates Range ID that's identified as hot range.	reserved
node_id	int32		node_id indicates the node that contains the current hot range.	reserved
qps	double		qps (queries per second) shows the amount of queries that interact with current range.	reserved
replica_node_ids	int32	repeated	replica_node_ids specifies the list of node ids that contain replicas with current hot range.	reserved
leaseholder_node_id	int32		leaseholder_node_id indicates the Node ID that is the current leaseholder for the given range.	reserved
schema_name	string		schema_name provides the name of schema (if exists) for table in current range.	reserved
store_id	int32		store_id indicates the Store ID where range is stored.	reserved
writes_per_second	double		writes_per_second is the recent number of keys written per second on this range.	reserved
reads_per_second	double		reads_per_second is the recent number of keys read per second on this range.	reserved
write_bytes_per_second	double		write_bytes_per_second is the recent number of bytes written per second on this range.	reserved
read_bytes_per_second	double		read_bytes_per_second is the recent number of bytes read per second on this range.	reserved
cpu_time_per_second	double		CPU time (ns) per second is the recent cpu usage per second on this range.	reserved
databases	string	repeated	Databases for the range.	reserved
tables	string	repeated	Tables for the range	reserved
indexes	string	repeated	Indexes for the range	reserved
desc	cockroach.roachpb.RangeDescriptor		Range Descriptor for the range	reserved

HotRangesResponseV2.ErrorsByNodeIdEntry

Field	Type	Label	Description	Support status
key	int32
value	string

KeyVisSamples

POST /_status/keyvissamples

Support status: reserved

Request Parameters

Response Parameters

KeyVisSamplesResponse returns a space-efficient representation of key visualizer samples. Spans are deduplicated, and are referenced by uuid.

Field	Type	Label	Description	Support status
pretty_key_for_uuid	KeyVisSamplesResponse.PrettyKeyForUuidEntry	repeated	pretty_key_for_uuid is a mapping of hex-encoded UUIDs to pretty keys.	reserved
sorted_pretty_keys	string	repeated		reserved
samples	KeyVisSamplesResponse.KeyVisSample	repeated		reserved

KeyVisSamplesResponse.PrettyKeyForUuidEntry

Field	Type	Label	Description	Support status
key	string
value	string

KeyVisSamplesResponse.KeyVisSample

Field	Type	Label	Description	Support status
timestamp	google.protobuf.Timestamp			reserved
buckets	KeyVisSamplesResponse.Bucket	repeated		reserved

KeyVisSamplesResponse.Bucket

Field	Type	Support status
start_key_id	bytes	reserved
end_key_id	bytes	reserved
requests	uint64	reserved

Range

GET /_status/range/{range_id}

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
range_id	int64			reserved

Response Parameters

Field	Type	Label	Description	Support status
node_id	int32		NodeID is the node that submitted all the requests.	reserved
range_id	int64			reserved
responses_by_node_id	RangeResponse.ResponsesByNodeIdEntry	repeated		reserved

RangeResponse.ResponsesByNodeIdEntry

Field	Type	Label	Description	Support status
key	int32
value	RangeResponse.NodeResponse

RangeResponse.NodeResponse

Field	Type	Label	Support status
response	bool		reserved
error_message	string		reserved
infos	RangeInfo	repeated	reserved

RangeInfo

Field	Type	Label	Description	Support status
span	PrettySpan			reserved
raft_state	RaftState			reserved
rac_status	RACStatus			reserved
state	cockroach.kv.kvserver.storagepb.RangeInfo			reserved
source_node_id	int32			reserved
source_store_id	int32			reserved
error_message	string			reserved
lease_history	cockroach.roachpb.Lease	repeated		reserved
problems	RangeProblems			reserved
stats	RangeStatistics			reserved
lease_status	cockroach.kv.kvserver.storagepb.LeaseStatus			reserved
quiescent	bool			reserved
ticking	bool			reserved
read_latches	int64			reserved
write_latches	int64			reserved
locks	int64			reserved
locks_with_wait_queues	int64			reserved
lock_wait_queue_waiters	int64			reserved
top_k_locks_by_wait_queue_waiters	RangeInfo.LockInfo	repeated		reserved
locality	Locality			reserved
is_leaseholder	bool			reserved
lease_valid	bool		Next tag: 26	reserved

PrettySpan

Field	Type	Label	Description	Support status
start_key	string			reserved
end_key	string			reserved

RaftState

RaftState gives internal details about a Raft group's state. Closely mirrors the upstream definitions in github.com/etcd-io/raft.

Field	Type	Label	Description	Support status
replica_id	uint64			reserved
hard_state	raftpb.HardState			reserved
lead	uint64		Lead is part of Raft's HardState. However, it used to be part of SoftState, so we keep it here as a separate field for compatibility.	reserved
state	string		State is part of Raft's SoftState. It's not an enum because this is primarily for ui consumption and there are issues associated with them.	reserved
applied	uint64			reserved
progress	RaftState.ProgressEntry	repeated		reserved
lead_transferee	uint64			reserved
lead_support_until	cockroach.util.hlc.Timestamp			reserved

RaftState.ProgressEntry

Field	Type	Label	Description	Support status
key	uint64
value	RaftState.Progress

RaftState.Progress

Field	Type	Support status
match	uint64	reserved
next	uint64	reserved
state	string	reserved
paused	bool	reserved
pending_snapshot	uint64	reserved

RACStatus

RACStatus contains the status of the Replication Admission Control component of a range.

Field	Type	Label	Support status
next_raft_index	uint64		reserved
force_flush_index	uint64		reserved
streams	RACStatus.StreamsEntry	repeated	reserved

RACStatus.StreamsEntry

Field	Type	Label	Description	Support status
key	uint64
value	RACStatus.Stream

RACStatus.Stream

Field	Type	Label	Support status
index_to_send	uint64		reserved
next_raft_index_initial	uint64		reserved
force_flush_stop_index	uint64		reserved
eval_tokens_held	int64	repeated	reserved
send_tokens_held	int64	repeated	reserved

RangeProblems

RangeProblems describes issues reported by a range. For internal use only.

Field	Type	Description	Support status
unavailable	bool		reserved
leader_not_lease_holder	bool		reserved
no_raft_leader	bool		reserved
underreplicated	bool		reserved
overreplicated	bool		reserved
no_lease	bool		reserved
quiescent_equals_ticking	bool	Quiescent ranges do not tick by definition, but we track this in two different ways and suspect that they're getting out of sync. If the replica's quiescent flag doesn't agree with the store's list of replicas that are ticking, warn about it.	reserved
raft_log_too_large	bool	When the raft log is too large, it can be a symptom of other issues.	reserved
circuit_breaker_error	bool		reserved
paused_followers	bool		reserved
range_too_large	bool		reserved

RangeStatistics

RangeStatistics describes statistics reported by a range. For internal use only.

Field	Type	Description	Support status
queries_per_second	double	Queries per second (batch requests) served by this range per second, averaged over the last 30 minute period.	reserved
writes_per_second	double	Writes per second served is the number of keys written to this range per second, averaged over the last 30 minute period.	reserved
requests_per_second	double	Requests per second is the number of requests served by this range per second, averaged over the last 30 minute period.	reserved
reads_per_second	double	Reads per second served is the number of keys read from this range per second, averaged over the last 30 minute period.	reserved
write_bytes_per_second	double	Writes (bytes) per second is the number of bytes written to this range per second, averaged over the last 30 minute period.	reserved
read_bytes_per_second	double	Reads (bytes) per second is the number of bytes read from this range per second, averaged over the last 30 minute period.	reserved
cpu_time_per_second	double	CPU time (ns) per second is the cpu usage of this range per second, averaged over the last 30 minute period.	reserved

RangeInfo.LockInfo

Field	Type	Support status
pretty_key	string	reserved
key	bytes	reserved
held	bool	reserved
waiters	int64	reserved
waiting_readers	int64	reserved
waiting_writers	int64	reserved

Locality

Locality is an ordered set of key value Tiers that describe a node's location. The tier keys should be the same across all nodes.

Field	Type	Label	Description	Support status
tiers	Tier	repeated		reserved

Tier

Tier represents one level of the locality hierarchy.

Field	Type	Label	Description	Support status
key	string		Key is the name of tier and should match all other nodes.	reserved
value	string		Value is node specific value corresponding to the key.	reserved

Diagnostics

GET /_status/diagnostics/{node_id}

Support status: reserved

Request Parameters

DiagnosticsRequest requests a diagnostics report.

Field	Type	Label	Description	Support status
node_id	string		node_id is a string so that "local" can be used to specify that no forwarding is necessary.	reserved

Response Parameters

Stores

GET /_status/stores/{node_id}

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string		node_id is a string so that "local" can be used to specify that no forwarding is necessary.	reserved

Response Parameters

Field	Type	Label	Description	Support status
stores	StoreDetails	repeated		reserved

StoreDetails

Field	Type	Description	Support status
store_id	int32		reserved
node_id	int32		reserved
encryption_status	bytes	encryption_status is a serialized storage/enginepb/stats.go::EncryptionStatus protobuf.	reserved
total_files	uint64	Basic file stats when encryption is enabled. Total files/bytes.	reserved
total_bytes	uint64		reserved
active_key_files	uint64	Files/bytes using the active data key.	reserved
active_key_bytes	uint64		reserved
dir	string	dir is the path to the store's data directory on the node.	reserved
wal_failover_path	string	wal_failover_path encodes the path to the secondary WAL directory used for failover in the event of high write latency to the primary WAL.	reserved

Statements

GET /_status/statements

Support status: reserved

Request Parameters

StatementsRequest is used by both tenant and node-level implementations to serve fan-out requests across multiple nodes or instances. When implemented on a node, the node_id field refers to the cluster nodes by their nodeID. When implemented on a tenant, the node_id field refers to the instanceIDs that identify individual tenant pods.

Field	Type	Description	Support status
node_id	string		reserved
combined	bool	If this field is set we will use the combined statements API instead.	reserved
start	int64	These fields are used for the combined statements API.	reserved
end	int64		reserved
fetch_mode	StatementsRequest.FetchMode		reserved

Response Parameters

Field	Type	Label	Description	Support status
statements	StatementsResponse.CollectedStatementStatistics	repeated		reserved
last_reset	google.protobuf.Timestamp		Timestamp of the last stats reset.	reserved
internal_app_name_prefix	string		If set and non-empty, indicates the prefix to application_name used for statements/queries issued internally by CockroachDB.	reserved
transactions	StatementsResponse.ExtendedCollectedTransactionStatistics	repeated	Transactions is transaction-level statistics for the collection of statements in this response.	reserved
stmts_total_runtime_secs	float			reserved
txns_total_runtime_secs	float			reserved
oldest_aggregated_ts_returned	google.protobuf.Timestamp		OldestAggregatedTsReturned is the timestamp of the oldest entry returned, or null if there is no data returned.	reserved
stmts_source_table	string		StmtsSourceTable returns the table used to return the statements data.	reserved
txns_source_table	string		TxnsSourceTable returns the table used to return the transactions data.	reserved

StatementsResponse.CollectedStatementStatistics

Field	Type	Label	Description	Support status
key	StatementsResponse.ExtendedStatementStatisticsKey			reserved
id	uint64			reserved
stats	cockroach.sql.StatementStatistics			reserved
txn_fingerprint_ids	uint64	repeated	In 23.1 we expect the response to only group on fingerprint_id and app_name in the overview page. We now return the aggregated list of unique txn fingerprint ids, leaving the txn_fingerprint_id field in the key empty.	reserved

StatementsResponse.ExtendedStatementStatisticsKey

Field	Type	Description	Support status
key_data	cockroach.sql.StatementStatisticsKey		reserved
node_id	int32		reserved
aggregated_ts	google.protobuf.Timestamp		reserved
aggregation_interval	google.protobuf.Duration	The aggregation duration.	reserved

StatementsResponse.ExtendedCollectedTransactionStatistics

Field	Type	Label	Description	Support status
stats_data	cockroach.sql.CollectedTransactionStatistics			reserved
node_id	int32			reserved

CombinedStatementStats

GET /_status/combinedstmts

Retrieve the combined in-memory and persisted statement stats by date range.

Support status: reserved

Request Parameters

Field	Type	Description	Support status
start	int64	Unix time range for aggregated statements.	reserved
end	int64		reserved
fetch_mode	CombinedStatementsStatsRequest.FetchMode	Note that if fetch_mode is set to transactions only, we will also include the statement statistics for the stmts in the transactions response. This is more of a hack-y method to get the complete stats for txns, because in the client we need to fill in some txn stats info from its stmt stats, such as the query string.

We prefer this hackier method right now to reduce surface area for backporting these changes, but in the future we will introduce more endpoints to properly organize these differing requests. TODO (xinhaoz) - Split this API into stmts and txns properly instead of using this param. | reserved | | limit | int64 | | | reserved |

CombinedStatementsStatsRequest.FetchMode

Field	Type	Label	Description	Support status
stats_type	CombinedStatementsStatsRequest.StatsType			reserved
sort	StatsSortOptions			reserved

Response Parameters

Field	Type	Label	Description	Support status
statements	StatementsResponse.CollectedStatementStatistics	repeated		reserved
last_reset	google.protobuf.Timestamp		Timestamp of the last stats reset.	reserved
internal_app_name_prefix	string		If set and non-empty, indicates the prefix to application_name used for statements/queries issued internally by CockroachDB.	reserved
transactions	StatementsResponse.ExtendedCollectedTransactionStatistics	repeated	Transactions is transaction-level statistics for the collection of statements in this response.	reserved
stmts_total_runtime_secs	float			reserved
txns_total_runtime_secs	float			reserved
oldest_aggregated_ts_returned	google.protobuf.Timestamp		OldestAggregatedTsReturned is the timestamp of the oldest entry returned, or null if there is no data returned.	reserved
stmts_source_table	string		StmtsSourceTable returns the table used to return the statements data.	reserved
txns_source_table	string		TxnsSourceTable returns the table used to return the transactions data.	reserved

StatementsResponse.CollectedStatementStatistics

Field	Type	Label	Description	Support status
key	StatementsResponse.ExtendedStatementStatisticsKey			reserved
id	uint64			reserved
stats	cockroach.sql.StatementStatistics			reserved
txn_fingerprint_ids	uint64	repeated	In 23.1 we expect the response to only group on fingerprint_id and app_name in the overview page. We now return the aggregated list of unique txn fingerprint ids, leaving the txn_fingerprint_id field in the key empty.	reserved

StatementsResponse.ExtendedStatementStatisticsKey

Field	Type	Description	Support status
key_data	cockroach.sql.StatementStatisticsKey		reserved
node_id	int32		reserved
aggregated_ts	google.protobuf.Timestamp		reserved
aggregation_interval	google.protobuf.Duration	The aggregation duration.	reserved

StatementsResponse.ExtendedCollectedTransactionStatistics

Field	Type	Label	Description	Support status
stats_data	cockroach.sql.CollectedTransactionStatistics			reserved
node_id	int32			reserved

StatementDetails

GET /_status/stmtdetails/{fingerprint_id}

Support status: reserved

Request Parameters

StatementDetailsRequest requests the details of a Statement, based on its keys.

Field	Type	Label	Description	Support status
fingerprint_id	string		fingerprint_id is generated by ConstructStatementFingerprintID using: query, failed, implicitTxn and database. So we don't need to add them to the request.	reserved
app_names	string	repeated		reserved
start	int64		Unix time range for aggregated statements.	reserved
end	int64			reserved

Response Parameters

Field	Type	Label	Description	Support status
statement	StatementDetailsResponse.CollectedStatementSummary		statement returns the total statistics for the statement.	reserved
statement_statistics_per_aggregated_ts	StatementDetailsResponse.CollectedStatementGroupedByAggregatedTs	repeated	statement_statistics_per_aggregated_ts returns the same statement from above, but with its statistics separated by the aggregated timestamp.	reserved
statement_statistics_per_plan_hash	StatementDetailsResponse.CollectedStatementGroupedByPlanHash	repeated	statement_statistics_per_plan_hash returns the same statement from above, but with its statistics separated by the plan hash.	reserved
internal_app_name_prefix	string		If set and non-empty, indicates the prefix to application_name used for statements/queries issued internally by CockroachDB.	reserved

StatementDetailsResponse.CollectedStatementSummary

Field	Type	Support status
metadata	cockroach.sql.AggregatedStatementMetadata	reserved
stats	cockroach.sql.StatementStatistics	reserved
aggregation_interval	google.protobuf.Duration	reserved

StatementDetailsResponse.CollectedStatementGroupedByAggregatedTs

Field	Type	Support status
metadata	cockroach.sql.AggregatedStatementMetadata	reserved
stats	cockroach.sql.StatementStatistics	reserved
aggregation_interval	google.protobuf.Duration	reserved
aggregated_ts	google.protobuf.Timestamp	reserved

StatementDetailsResponse.CollectedStatementGroupedByPlanHash

Field	Type	Label	Support status
metadata	cockroach.sql.AggregatedStatementMetadata		reserved
stats	cockroach.sql.StatementStatistics		reserved
aggregation_interval	google.protobuf.Duration		reserved
explain_plan	string		reserved
plan_hash	uint64		reserved
index_recommendations	string	repeated	reserved

CreateStatementDiagnosticsReport

POST /_status/stmtdiagreports

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
statement_fingerprint	string			reserved
min_execution_latency	google.protobuf.Duration		MinExecutionLatency, when non-zero, indicates the minimum execution latency of a query for which to collect the diagnostics report. In other words, if a query executes faster than this threshold, then the diagnostics report is not collected on it, and we will try to get a bundle the next time we see the query fingerprint.

NB: if MinExecutionLatency is non-zero, then all queries that match the fingerprint will be traced until a slow enough query comes along. This tracing might have some performance overhead. | reserved | | expires_after | google.protobuf.Duration | | ExpiresAfter, when non-zero, sets the expiration interval of this request. | reserved | | sampling_probability | double | | SamplingProbability controls how likely we are to try and collect a diagnostics report for a given execution. The semantics with MinExecutionLatency are worth noting (and perhaps simplifying?): - If SamplingProbability is zero, we're always sampling. This is for compatibility with pre-22.2 versions where this parameter was not available. - If SamplingProbability is non-zero, MinExecutionLatency must be non-zero. We'll sample stmt executions with the given probability until: (a) we capture one that exceeds MinExecutionLatency, or (b) we hit the ExpiresAfter point.

SamplingProbability lets users control at a per-stmt granularity how much collection overhead is acceptable to try an capture an outlier execution for further analysis (are high p99.9s due to latch waits? racing with split transfers?). A high sampling rate can capture a trace sooner, but the added overhead may also cause the trace to be non-representative if the tracing overhead across all requests is causing resource saturation (network, memory) and resulting in slowdown.

TODO(irfansharif): Wire this up to the UI code. When selecting the latency threshold, we should want to force specifying a sampling probability.

TODO(irfansharif): We could do better than a hard-coded default value for probability (100% could be too high-overhead so probably not the right one). Strawman: could consider the recent request rate for the fingerprint (say averaged over the last 10m? 30m?), consider what %-ile the latency target we're looking to capture is under, and suggest a sampling probability that gets you at least one trace in the next T seconds with 95% likelihood? Or provide a hint for how long T is for the currently chosen sampling probability. | reserved | | plan_gist | string | | PlanGist, when set, indicates a particular plan that we want collect diagnostics for. This can be useful when a single fingerprint can result in multiple plans.

Response Parameters

Field	Type	Label	Description	Support status
report	StatementDiagnosticsReport			reserved

StatementDiagnosticsReport

Field	Type	Description	Support status
id	int64		reserved
completed	bool		reserved
statement_fingerprint	string		reserved
statement_diagnostics_id	int64		reserved
requested_at	google.protobuf.Timestamp		reserved
min_execution_latency	google.protobuf.Duration		reserved
expires_at	google.protobuf.Timestamp	TODO(yuzefovich): should we populate plan_gist, anti_plan_gist, redacted, and username fields?	reserved

CancelStatementDiagnosticsReport

POST /_status/stmtdiagreports/cancel

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
request_id	int64			reserved

Response Parameters

Field	Type	Label	Description	Support status
canceled	bool		canceled indicates whether the request for the given fingerprint was actually canceled.	reserved
error	string		error is set only if canceled is false.	reserved

StatementDiagnosticsRequests

GET /_status/stmtdiagreports

Support status: reserved

Request Parameters

Response Parameters

Field	Type	Label	Description	Support status
reports	StatementDiagnosticsReport	repeated		reserved

StatementDiagnosticsReport

Field	Type	Description	Support status
id	int64		reserved
completed	bool		reserved
statement_fingerprint	string		reserved
statement_diagnostics_id	int64		reserved
requested_at	google.protobuf.Timestamp		reserved
min_execution_latency	google.protobuf.Duration		reserved
expires_at	google.protobuf.Timestamp	TODO(yuzefovich): should we populate plan_gist, anti_plan_gist, redacted, and username fields?	reserved

StatementDiagnostics

GET /_status/stmtdiag/{statement_diagnostics_id}

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
statement_diagnostics_id	int64			reserved

Response Parameters

Field	Type	Label	Description	Support status
diagnostics	StatementDiagnostics			reserved

StatementDiagnostics

Field	Type	Support status
id	int64	reserved
statement_fingerprint	string	reserved
collected_at	google.protobuf.Timestamp	reserved

CreateTransactionDiagnosticsReport

POST /_status/txndiagreports

Support status: reserved

Request Parameters

createTransactionDiagnosticsReportRequest is a message that captures a user's requst to capture a transaction diagnostic bundle.

Field	Type	Label	Support status
transaction_fingerprint_id	bytes		reserved
statement_fingerprint_ids	bytes	repeated	reserved
min_execution_latency	google.protobuf.Duration		reserved
expires_at	google.protobuf.Duration		reserved
sampling_probability	double		reserved
redacted	bool		reserved

Response Parameters

Field	Type	Label	Description	Support status
report	TransactionDiagnosticsReport			reserved

TransactionDiagnosticsReport

TransactionDiagnosticsReport is a message that represents a diagnostics capture request for a given transaction.

Field	Type	Label	Description	Support status
id	int64			reserved
completed	bool			reserved
transaction_fingerprint_id	bytes		TODO(davidh): should these be strings or int64??? I think bytes is most correct.	reserved
statement_fingerprint_ids	bytes	repeated		reserved
transaction_fingerprint	string			reserved
transaction_diagnostics_id	int64			reserved
requested_at	google.protobuf.Timestamp			reserved
min_execution_latency	google.protobuf.Duration			reserved
expires_at	google.protobuf.Timestamp			reserved
sampling_probability	double			reserved
redacted	bool			reserved
username	string			reserved

CancelTransactionDiagnosticsReport

POST /_status/txndiagreports/cancel

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
request_id	int64			reserved

Response Parameters

Field	Type	Label	Description	Support status
canceled	bool		canceled indicates whether the request for the given fingerprint was actually canceled.	reserved
error	string		error is set only if canceled is false.	reserved

TransactionDiagnosticsRequests

GET /_status/txndiagreports

Support status: reserved

Request Parameters

Response Parameters

Field	Type	Label	Description	Support status
reports	TransactionDiagnosticsReport	repeated		reserved

TransactionDiagnosticsReport

TransactionDiagnosticsReport is a message that represents a diagnostics capture request for a given transaction.

Field	Type	Label	Description	Support status
id	int64			reserved
completed	bool			reserved
transaction_fingerprint_id	bytes		TODO(davidh): should these be strings or int64??? I think bytes is most correct.	reserved
statement_fingerprint_ids	bytes	repeated		reserved
transaction_fingerprint	string			reserved
transaction_diagnostics_id	int64			reserved
requested_at	google.protobuf.Timestamp			reserved
min_execution_latency	google.protobuf.Duration			reserved
expires_at	google.protobuf.Timestamp			reserved
sampling_probability	double			reserved
redacted	bool			reserved
username	string			reserved

JobRegistryStatus

GET /_status/job_registry/{node_id}

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string			reserved

Response Parameters

Field	Type	Label	Description	Support status
node_id	int32			reserved
running_jobs	JobRegistryStatusResponse.Job	repeated		reserved

JobRegistryStatusResponse.Job

Field	Type	Label	Description	Support status
id	int64			reserved

JobStatus

GET /_status/job/{job_id}

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
job_id	int64			reserved

Response Parameters

Field	Type	Label	Description	Support status
job	cockroach.sql.jobs.jobspb.Job			reserved

ResetSQLStats

POST /_status/resetsqlstats

Support status: reserved

Request Parameters

Request object for issuing a SQL stats reset request.

Field	Type	Label	Description	Support status
node_id	string			reserved
reset_persisted_stats	bool		reset_persisted_stats specifies if the persisted SQL Stats will be reset along with the in-memory SQL stats.	reserved

Response Parameters

Response object returned by ResetSQLStats.

DrainSqlStats

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string			reserved

Response Parameters

Field	Type	Label	Support status
statements	cockroach.sql.CollectedStatementStatistics	repeated	reserved
transactions	cockroach.sql.CollectedTransactionStatistics	repeated	reserved
fingerprint_count	int64		reserved

IndexUsageStatistics

GET /_status/indexusagestatistics

Support status: reserved

Request Parameters

Request object for issuing IndexUsageStatistics request.

Field	Type	Label	Description	Support status
node_id	string		node_id is the ID of the node where the stats data shall be retrieved from. If this is left empty, the cluster-wide aggregated result will be returned.	reserved

Response Parameters

Response object returned by IndexUsageStatistics.

Field	Type	Label	Description	Support status
statistics	cockroach.sql.CollectedIndexUsageStatistics	repeated		reserved
last_reset	google.protobuf.Timestamp		Timestamp of the last index usage stats reset.	reserved

ResetIndexUsageStats

POST /_status/resetindexusagestats

Support status: reserved

Request Parameters

Request object for issuing a index usage stats reset request.

Field	Type	Label	Description	Support status
node_id	string			reserved
cluster_reset_start_time	google.protobuf.Timestamp		Timestamp for the start time of the latest reset index usage statistics request on the cluster.	reserved

Response Parameters

Response object returned by ResetIndexUsageStatsRequest.

TableIndexStats

GET /_status/databases/{database}/tables/{table}/indexstats

TableIndexStats retrieves index stats for a table.

Support status: reserved

Request Parameters

Request object for issuing TableIndexStatsRequest request.

Field	Type	Label	Description	Support status
database	string		database is the name of the database that contains the table we're interested in.	reserved
table	string		table is the name of the table that we're querying. Table may be schema-qualified (schema.table) and each name component that contains sql unsafe characters such as . or uppercase letters must be surrounded in double quotes like "naughty schema".table.	reserved

Response Parameters

Response object returned by TableIndexStatsResponse.

Field	Type	Label	Description	Support status
statistics	TableIndexStatsResponse.ExtendedCollectedIndexUsageStatistics	repeated		reserved
last_reset	google.protobuf.Timestamp		Timestamp of the latest reset index usage statistics request.	reserved
index_recommendations	cockroach.sql.IndexRecommendation	repeated		reserved
database_id	int32		database_id is the ID of the database that contains the table.	reserved

TableIndexStatsResponse.ExtendedCollectedIndexUsageStatistics

Field	Type	Description	Support status
statistics	cockroach.sql.CollectedIndexUsageStatistics		reserved
index_name	string	index_name is the name of the index.	reserved
index_type	string	index_type is the type of the index i.e. primary, secondary.	reserved
create_statement	string	create_statement is the SQL statement that would re-create the current index if executed.	reserved
created_at	google.protobuf.Timestamp	created_at is an approximate timestamp at which the index was created. Note that it may not always be populated.	reserved
index_id	string	index_id is the ID of the index.	reserved
table_id	string	table_id is the ID of the table which the index belongs to.	reserved

UserSQLRoles

GET /_status/sqlroles

Support status: reserved

Request Parameters

UserSQLRolesRequest requests a list of roles of the logged in SQL user.

Response Parameters

UserSQLRolesResponse returns a list of roles for the logged SQL user.

Field	Type	Label	Description	Support status
roles	string	repeated	roles is a list of roles for the SQL user.	reserved

TxnIDResolution

TxnIDResolution is used by the contention event store to resolve transaction ID into transaction fingerprint IDs. This RPC does not have a corresponding HTTP endpoint on purpose, since DB Console should never directly query this endpoint.

The API contract is the following:

if the server can resolve the transaction IDs in the RPC request, it will be returned in the RPC response.
if the server is not able to resolve the transaction IDs, it will instructs the transaction ID cache to drain its write buffer. (Since transaction ID cache's write path is asynchronous, the transaction ID requested by the client might not be available in the cache yet). Client is responsible to perform retries if the requested transaction ID is not returned in the RPC response.

Support status: reserved

Request Parameters

Request object for issuing Transaction ID Resolution.

Field	Type	Label	Description	Support status
coordinator_id	string		coordinator_id is either the NodeID or SQLInstanceID depending on whether the transaction is executed on a system tenant or a regular tenant.	reserved
txnIDs	bytes	repeated		reserved

Response Parameters

Response object for issuing Transaction ID Resolution.

Field	Type	Label	Description	Support status
resolvedTxnIDs	cockroach.sql.contentionpb.ResolvedTxnID	repeated		reserved

TransactionContentionEvents

GET /_status/transactioncontentionevents

TransactionContentionEvents returns a list of un-aggregated contention events sorted by the collection timestamp.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string			reserved

Response Parameters

Field	Type	Label	Description	Support status
events	cockroach.sql.contentionpb.ExtendedContentionEvent	repeated		reserved

ListExecutionInsights

ListExecutionInsights returns potentially problematic statements cluster-wide, along with actions we suggest the application developer might take to remedy them.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string		node_id is a string so that "local" can be used to specify that no forwarding is necessary.	reserved

Response Parameters

Field	Type	Label	Description	Support status
insights	cockroach.sql.insights.Insight	repeated	insights lists any potentially problematic statements and actions we suggest the application developer might take to remedy them.	reserved
errors	cockroach.errorspb.EncodedError	repeated	errors holds any errors that occurred during fan-out calls to other nodes.	reserved

NetworkConnectivity

GET /_status/connectivity

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string			reserved

Response Parameters

Field	Type	Label	Description	Support status
connections	NetworkConnectivityResponse.ConnectionsEntry	repeated		reserved
errors_by_node_id	NetworkConnectivityResponse.ErrorsByNodeIdEntry	repeated	errors contains any errors that occurred during fan-out calls to other nodes.	reserved

NetworkConnectivityResponse.ConnectionsEntry

Field	Type	Label	Description	Support status
key	int32
value	NetworkConnectivityResponse.Connectivity

NetworkConnectivityResponse.Connectivity

Field	Type	Label	Description	Support status
peers	NetworkConnectivityResponse.Connectivity.PeersEntry	repeated		reserved

NetworkConnectivityResponse.Connectivity.PeersEntry

Field	Type	Label	Description	Support status
key	int32
value	NetworkConnectivityResponse.Peer

NetworkConnectivityResponse.Peer

Field	Type	Support status
latency	google.protobuf.Duration	reserved
status	NetworkConnectivityResponse.ConnectionStatus	reserved
address	string	reserved
locality	cockroach.roachpb.Locality	reserved
error	string	reserved

NetworkConnectivityResponse.ErrorsByNodeIdEntry

Field	Type	Label	Description	Support status
key	int32
value	string

RequestJobProfilerExecutionDetails

GET /_status/request_job_profiler_execution_details/{job_id}

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
job_id	int64			reserved

Response Parameters

GetJobProfilerExecutionDetails

GET /_status/job_profiler_execution_details/{job_id}

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
job_id	int64			reserved
filename	string			reserved

Response Parameters

Field	Type	Label	Description	Support status
data	bytes			reserved

ListJobProfilerExecutionDetails

GET /_status/list_job_profiler_execution_details/{job_id}

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
job_id	int64			reserved

Response Parameters

Field	Type	Label	Description	Support status
files	string	repeated		reserved

UpdateTableMetadataCache

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
local	bool		If true, the server will attempt to send a signal to the table metadata job by notifying the channel set on the status server.	reserved

Response Parameters

GetThrottlingMetadata

GET /_status/throttling

GetThrottlingMetadata is used by the DB Console to retrieve information regarding current or upcoming throttling the cluster may experience.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
node_id	string			reserved

Response Parameters

GetThrottlingMetadataResponse contains all information necessary to show throttling warnings and alerts in DB Console.

Field	Type	Label	Description	Support status
throttled	bool		throttled is true if at least one node in the cluster is actively being throttled.	reserved
throttleExplanation	string		if throttled is true, this will contain a string explaning why, generated from the SQL enforcer.	reserved
hasGracePeriod	bool		hasGracePeriod is true if the cluster has an active grace period before throttling kicks in after license expiry. Enterprise licenses do not have grace periods when they expire.	reserved
gracePeriodEndSeconds	int64		gracePeriodEndSeconds is the unix timestamp when the grace period ends.	reserved
hasTelemetryDeadline	bool		hasTelemetryDeadline is true if this cluster requires telemetry to be delivered.	reserved
telemetryDeadlineSeconds	int64		telemetryDeadlineSeconds is the unix timestamp when the telemetry deadline must be met. After this the cluster will be throttled.	reserved
lastTelemetryReceivedSeconds	int64		lastTelemetryReceivedSeconds is the unix timestamp when we last delivered telemetry.	reserved
nodeIdsWithTelemetryProblems	string	repeated	nodeIdsWithTelemetryProblems collects a list of nodes that are delinquent with telemetry. This is useful for reporting because the cluster could have partial telemetry delivery failure and it's helpful to surface this in DB Console.	reserved

Users

GET /_admin/v1/users

URL: /_admin/v1/users

Support status: reserved

Request Parameters

UsersRequest requests a list of users.

Response Parameters

UsersResponse returns a list of users.

Field	Type	Label	Description	Support status
users	UsersResponse.User	repeated	usernames is a list of users for the CockroachDB cluster.	reserved

UsersResponse.User

User is a CockroachDB user.

Field	Type	Label	Description	Support status
username	string			reserved

Databases

GET /_admin/v1/databases

URL: /_admin/v1/databases

Support status: reserved

Request Parameters

DatabasesRequest requests a list of databases.

Response Parameters

DatabasesResponse contains a list of databases.

Field	Type	Label	Description	Support status
databases	string	repeated		reserved

DatabaseDetails

GET /_admin/v1/databases/{database}

Example URL: /_admin/v1/databases/system

Support status: reserved

Request Parameters

DatabaseDetailsRequest requests detailed information about the specified database

Field	Type	Label	Description	Support status
database	string		database is the name of the database we are querying.	reserved
include_stats	bool		Setting this flag includes a computationally-expensive stats field in the response.	reserved

Response Parameters

DatabaseDetailsResponse contains grant information, table names, zone configuration, and size statistics for a database.

Field	Type	Label	Description	Support status
grants	DatabaseDetailsResponse.Grant	repeated	grants are the results of SHOW GRANTS for this database.	reserved
table_names	string	repeated	table_names contains the names of all tables in this database. Note that all responses will be schema-qualified (schema.table) and that every schema or table that contains a "sql unsafe character" such as uppercase letters or dots will be surrounded with double quotes, such as "naughty schema".table.	reserved
descriptor_id	int64		descriptor_id is an identifier used to uniquely identify this database.	reserved
zone_config	cockroach.config.zonepb.ZoneConfig		The zone configuration in effect for this database.	reserved
zone_config_level	ZoneConfigurationLevel		The level at which this object's zone configuration is set.	reserved
stats	DatabaseDetailsResponse.Stats		Size information about the database, present only when explicitly requested.	reserved

DatabaseDetailsResponse.Grant

Field	Type	Label	Description	Support status
user	string		user is the user that this grant applies to.	reserved
privileges	string	repeated	privileges are the abilities this grant gives to the user.	reserved

DatabaseDetailsResponse.Stats

Field	Type	Label	Description	Support status
missing_tables	DatabaseDetailsResponse.Stats.MissingTable	repeated	A list of tables that exist in the database, but for which stats could not be loaded due to failures during this request.	reserved
range_count	int64		The number of ranges, as determined from a query of range meta keys, across all tables.	reserved
approximate_disk_bytes	uint64		An approximation of the disk space (in bytes) used for all replicas of all tables across the cluster.	reserved
node_ids	int32	repeated	node_ids is the ordered list of node ids on which data is stored.	reserved
num_index_recommendations	int32			reserved

DatabaseDetailsResponse.Stats.MissingTable

A table which exists in the database, but for which we could not load stats during this request.

Field	Type	Label	Description	Support status
name	string		The name of the table for which we could not load stats.	reserved
error_message	string		The error message that resulted when the request for this table failed.	reserved

TableDetails

GET /_admin/v1/databases/{database}/tables/{table}

Example URL: /_admin/v1/databases/system/tables/ui

Support status: reserved

Request Parameters

TableDetailsRequest is a request for detailed information about a table.

Field	Type	Label	Description	Support status
database	string		database is the name of the database that contains the table we're interested in.	reserved
table	string		table is the name of the table that we're querying. Table may be schema-qualified (schema.table) and each name component that contains sql unsafe characters such as . or uppercase letters must be surrounded in double quotes like "naughty schema".table.	reserved

Response Parameters

TableDetailsResponse contains grants, column names, and indexes for a table.

Field	Type	Label	Description	Support status
grants	TableDetailsResponse.Grant	repeated		reserved
columns	TableDetailsResponse.Column	repeated		reserved
indexes	TableDetailsResponse.Index	repeated		reserved
range_count	int64		range_count is the size of the table in ranges. This provides a rough estimate of the storage requirements for the table. TODO(mrtracy): The TableStats method also returns a range_count field which is more accurate than this one; TableDetails calculates this number using a potentially faster method that is subject to cache staleness. We should consider removing or renaming this field to reflect that difference. See GitHub issue #5435 for more information.	reserved
create_table_statement	string		create_table_statement is the output of "SHOW CREATE" for this table; it is a SQL statement that would re-create the table's current schema if executed.	reserved
zone_config	cockroach.config.zonepb.ZoneConfig		The zone configuration in effect for this table.	reserved
zone_config_level	ZoneConfigurationLevel		The level at which this object's zone configuration is set.	reserved
descriptor_id	int64		descriptor_id is an identifier used to uniquely identify this table.	reserved
configure_zone_statement	string		configure_zone_statement is the output of "SHOW ZONE CONFIGURATION FOR TABLE" for this table. It is a SQL statement that would re-configure the table's current zone if executed.	reserved
stats_last_created_at	google.protobuf.Timestamp		stats_last_created_at is the time at which statistics were last created.	reserved
has_index_recommendations	bool		has_index_recommendations notifies if the there are index recommendations on this table.	reserved
data_total_bytes	int64		data_total_bytes is the size in bytes of live and non-live data on the table.	reserved
data_live_bytes	int64		data_live_bytes is the size in bytes of live (non MVCC) data on the table.	reserved
data_live_percentage	float		data_live_percentage is the percentage of live (non MVCC) data on the table.	reserved

TableDetailsResponse.Grant

Grant is an entry from SHOW GRANTS.

Field	Type	Label	Description	Support status
user	string		user is the user that this grant applies to.	reserved
privileges	string	repeated	privileges are the abilities this grant gives to the user.	reserved

TableDetailsResponse.Column

Field	Type	Description	Support status
name	string	name is the name of the column.	reserved
type	string	type is the SQL type (INT, STRING, etc.) of this column.	reserved
nullable	bool	nullable is whether this column can contain NULL.	reserved
default_value	string	default_value is the default value of this column.	reserved
generation_expression	string	generation_expression is the generator expression if the column is computed.	reserved
hidden	bool	hidden is whether this column is hidden.	reserved

TableDetailsResponse.Index

Field	Type	Description	Support status
name	string	name is the name of this index.	reserved
unique	bool	unique is whether this a unique index (i.e. CREATE UNIQUE INDEX).	reserved
seq	int64	seq is an internal variable that's passed along.	reserved
column	string	column is the column that this index indexes.	reserved
direction	string	direction is either "ASC" (ascending) or "DESC" (descending).	reserved
storing	bool	storing is an internal variable that's passed along.	reserved
implicit	bool	implicit is an internal variable that's passed along.	reserved

TableStats

GET /_admin/v1/databases/{database}/tables/{table}/stats

Example URL: /_admin/v1/databases/system/tables/ui/stats

Support status: reserved

Request Parameters

TableStatsRequest is a request for detailed, computationally expensive information about a table.

Field	Type	Label	Description	Support status
database	string		database is the name of the database that contains the table we're interested in.	reserved
table	string		table is the name of the table that we're querying. Table may be schema-qualified (schema.table) and each name component that contains sql unsafe characters such as . or uppercase letters must be surrounded in double quotes like "naughty schema".table.	reserved

Response Parameters

TableStatsResponse contains detailed, computationally expensive information about a table.

Field	Type	Label	Description	Support status
range_count	int64		range_count is the number of ranges, as determined from a query of range meta keys.	reserved
replica_count	int64		replica_count is the number of replicas of any range of this table, as found by querying nodes which are known to have replicas. When compared with range_count, this can be used to estimate the current replication factor of the table.	reserved
node_count	int64		node_count is the number of nodes which contain data for this table, according to a query of range meta keys.	reserved
stats	cockroach.storage.enginepb.MVCCStats		stats is the summation of MVCCStats for all replicas of this table across the cluster.	reserved
approximate_disk_bytes	uint64		approximate_disk_bytes is an approximation of the disk space (in bytes) used for all replicas of this table across the cluster.	reserved
missing_nodes	TableStatsResponse.MissingNode	repeated	A list of nodes which should contain data for this table (according to cluster metadata), but could not be contacted during this request.	reserved
node_ids	int32	repeated	node_ids is the ordered list of node ids on which the table data is stored.	reserved

TableStatsResponse.MissingNode

MissingNode represents information on a node which should contain data for this table, but could not be contacted during this request.

Field	Type	Label	Description	Support status
node_id	string		The ID of the missing node.	reserved
error_message	string		The error message that resulted when the query sent to this node failed.	reserved

NonTableStats

GET /_admin/v1/nontablestats

Example URL: /_admin/v1/nontablestats

Support status: reserved

Request Parameters

NonTableStatsRequest requests statistics on cluster data ranges that do not belong to SQL tables.

Response Parameters

NonTableStatsResponse returns statistics on various cluster data ranges that do not belong to SQL tables. The statistics for each range are returned as a TableStatsResponse.

Field	Type	Label	Description	Support status
time_series_stats	TableStatsResponse		Information on time series ranges.	reserved
internal_use_stats	TableStatsResponse		Information for remaining (non-table, non-time-series) ranges.	reserved

TableStatsResponse

TableStatsResponse contains detailed, computationally expensive information about a table.

Field	Type	Label	Description	Support status
range_count	int64		range_count is the number of ranges, as determined from a query of range meta keys.	reserved
replica_count	int64		replica_count is the number of replicas of any range of this table, as found by querying nodes which are known to have replicas. When compared with range_count, this can be used to estimate the current replication factor of the table.	reserved
node_count	int64		node_count is the number of nodes which contain data for this table, according to a query of range meta keys.	reserved
stats	cockroach.storage.enginepb.MVCCStats		stats is the summation of MVCCStats for all replicas of this table across the cluster.	reserved
approximate_disk_bytes	uint64		approximate_disk_bytes is an approximation of the disk space (in bytes) used for all replicas of this table across the cluster.	reserved
missing_nodes	TableStatsResponse.MissingNode	repeated	A list of nodes which should contain data for this table (according to cluster metadata), but could not be contacted during this request.	reserved
node_ids	int32	repeated	node_ids is the ordered list of node ids on which the table data is stored.	reserved

TableStatsResponse.MissingNode

MissingNode represents information on a node which should contain data for this table, but could not be contacted during this request.

Field	Type	Label	Description	Support status
node_id	string		The ID of the missing node.	reserved
error_message	string		The error message that resulted when the query sent to this node failed.	reserved

TableStatsResponse

TableStatsResponse contains detailed, computationally expensive information about a table.

Field	Type	Label	Description	Support status
range_count	int64		range_count is the number of ranges, as determined from a query of range meta keys.	reserved
replica_count	int64		replica_count is the number of replicas of any range of this table, as found by querying nodes which are known to have replicas. When compared with range_count, this can be used to estimate the current replication factor of the table.	reserved
node_count	int64		node_count is the number of nodes which contain data for this table, according to a query of range meta keys.	reserved
stats	cockroach.storage.enginepb.MVCCStats		stats is the summation of MVCCStats for all replicas of this table across the cluster.	reserved
approximate_disk_bytes	uint64		approximate_disk_bytes is an approximation of the disk space (in bytes) used for all replicas of this table across the cluster.	reserved
missing_nodes	TableStatsResponse.MissingNode	repeated	A list of nodes which should contain data for this table (according to cluster metadata), but could not be contacted during this request.	reserved
node_ids	int32	repeated	node_ids is the ordered list of node ids on which the table data is stored.	reserved

Events

GET /_admin/v1/events

Example URLs: Example URLs:

/_admin/v1/events
/_admin/v1/events?limit=100
/_admin/v1/events?type=create_table
/_admin/v1/events?type=create_table&limit=100

Support status: reserved

Request Parameters

EventsRequest is a request for event log entries, optionally filtered by the specified event type.

Field	Type	Description	Support status
type	string		reserved
limit	int32	limit is the total number of results that are retrieved by the query. If this is omitted or set to 0, the default maximum number of results are returned. When set to > 0, at most only that number of results are returned. When set to < 0, an unlimited number of results are returned.	reserved
unredacted_events	bool	unredacted_events indicates that the values in the events should not be redacted. The default is to redact, so that older versions of `cockroach zip` do not see un-redacted values by default. For good security, this field is only obeyed by the server after checking that the client of the RPC is an admin user.	reserved

Response Parameters

EventsResponse contains a set of event log entries. This is always limited to the latest N entries (N is enforced in the associated endpoint).

Field	Type	Label	Description	Support status
events	EventsResponse.Event	repeated		reserved

EventsResponse.Event

Field	Type	Description	Support status
timestamp	google.protobuf.Timestamp	timestamp is the time at which the event occurred.	reserved
event_type	string	event_type is the type of the event (e.g. "create_table", "drop_table".	reserved
reporting_id	int64	reporting_id is the reporting ID for this event.	reserved
info	string	info has more detailed information for the event. The contents vary depending on the event.	reserved
unique_id	bytes	unique_id is a unique identifier for this event.	reserved

SetUIData

POST /_admin/v1/uidata

This requires a POST. Because of the libraries we're using, the POST body must be in the following format:

{"key_values": { "key1": "base64_encoded_value1"}, ... { "keyN": "base64_encoded_valueN"}, }

Note that all keys are quoted strings and that all values are base64- encoded.

Together, SetUIData and GetUIData provide access to a "cookie jar" for the admin UI. The structure of the underlying data is meant to be opaque to the server.

Support status: reserved

Request Parameters

SetUIDataRequest stores the given key/value pairs in the system.ui table.

Field	Type	Label	Description	Support status
key_values	SetUIDataRequest.KeyValuesEntry	repeated	key_values is a map of keys to bytes values. Each key will be stored with its corresponding value as a separate row in system.ui.	reserved

SetUIDataRequest.KeyValuesEntry

Field	Type	Label	Description	Support status
key	string
value	bytes

Response Parameters

SetUIDataResponse is currently an empty response.

GetUIData

GET /_admin/v1/uidata

Example URLs:

/_admin/v1/uidata?keys=MYKEY
/_admin/v1/uidata?keys=MYKEY1&keys=MYKEY2

Yes, it's a little odd that the query parameter is named "keys" instead of "key". I would've preferred that the URL parameter be named "key". However, it's clearer for the protobuf field to be named "keys," which makes the URL parameter "keys" as well.

Support status: reserved

Request Parameters

GETUIDataRequest requests the values for the given keys from the system.ui table.

Field	Type	Label	Description	Support status
keys	string	repeated		reserved

Response Parameters

GetUIDataResponse contains the requested values and the times at which the values were last updated.

Field	Type	Label	Description	Support status
key_values	GetUIDataResponse.KeyValuesEntry	repeated	key_values maps keys to their retrieved values. If this doesn't contain a a requested key, that key was not found.	reserved

GetUIDataResponse.KeyValuesEntry

Field	Type	Label	Description	Support status
key	string
value	GetUIDataResponse.Value

GetUIDataResponse.Value

Field	Type	Label	Description	Support status
value	bytes		value is the value of the requested key.	reserved
last_updated	google.protobuf.Timestamp		last_updated is the time at which the value was last updated.	reserved

Cluster

GET /_admin/v1/cluster

Cluster returns metadata for the cluster.

Support status: reserved

Request Parameters

ClusterRequest requests metadata for the cluster.

Response Parameters

ClusterResponse contains metadata for the cluster.

Field	Type	Description	Support status
cluster_id	string	The unique ID used to identify this cluster.	reserved
reporting_enabled	bool	True if diagnostics reporting is enabled for the cluster.	reserved
enterprise_enabled	bool	True if enterprise features are enabled for the cluster.	reserved

Settings

GET /_admin/v1/settings

Settings returns the cluster-wide settings for the cluster.

Support status: reserved

Request Parameters

SettingsRequest inquires what are the current settings in the cluster.

Field	Type	Label	Description	Support status
keys	string	repeated	The array of setting keys or names to retrieve. An empty keys array means "all".	reserved

Response Parameters

SettingsResponse is the response to SettingsRequest.

Field	Type	Label	Description	Support status
key_values	SettingsResponse.KeyValuesEntry	repeated		reserved

SettingsResponse.KeyValuesEntry

Field	Type	Label	Description	Support status
key	string
value	SettingsResponse.Value

SettingsResponse.Value

Field	Type	Description	Support status
value	string	The value of the setting.	reserved
type	string	The type of the setting.	reserved
description	string	An extended description text.	reserved
public	bool	Whether the setting is public or reserved.	reserved
last_updated	google.protobuf.Timestamp	When the setting was last updated.	reserved
name	string	The setting name for display purposes.	reserved

Health

GET /health

Health returns liveness for the node target of the request.

Support status: public

Request Parameters

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.

Field	Type	Label	Description	Support status
ready	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

Response Parameters

HealthResponse is the response to HealthRequest. It currently does not contain any information.

Liveness

GET /_admin/v1/liveness

Liveness returns the liveness state of all nodes on the cluster.

Support status: reserved

Request Parameters

LivenessRequest requests liveness data for all nodes on the cluster.

Response Parameters

LivenessResponse contains the liveness status of each node on the cluster.

Field	Type	Label	Description	Support status
livenesses	cockroach.kv.kvserver.liveness.livenesspb.Liveness	repeated		reserved
statuses	LivenessResponse.StatusesEntry	repeated		reserved

LivenessResponse.StatusesEntry

Field	Type	Label	Description	Support status
key	int32
value	cockroach.kv.kvserver.liveness.livenesspb.NodeLivenessStatus

Jobs

GET /_admin/v1/jobs

Jobs returns the job records for all jobs of the given status and type.

Support status: reserved

Request Parameters

JobsRequest requests system job information of the given status and type.

Field	Type	Support status
limit	int32	reserved
status	string	reserved
type	cockroach.sql.jobs.jobspb.Type	reserved

Response Parameters

JobsResponse contains the job record for each matching job.

Field	Type	Label	Description	Support status
jobs	JobResponse	repeated		reserved
earliest_retained_time	google.protobuf.Timestamp			reserved

JobResponse

JobResponse contains the job record for a job.

Field	Type	Label	Description	Support status
id	int64			reserved
type	string			reserved
description	string			reserved
statement	string			reserved
username	string			reserved
descriptor_ids	uint32	repeated		reserved
status	string			reserved
created	google.protobuf.Timestamp			reserved
started	google.protobuf.Timestamp			reserved
finished	google.protobuf.Timestamp			reserved
modified	google.protobuf.Timestamp			reserved
fraction_completed	float			reserved
error	string			reserved
highwater_timestamp	google.protobuf.Timestamp		highwater_timestamp is the highwater timestamp returned as normal timestamp. This is appropriate for display to humans.	reserved
highwater_decimal	string		highwater_decimal is the highwater timestamp in the proprietary decimal form used by logical timestamps internally. This is appropriate to pass to a "AS OF SYSTEM TIME" SQL statement.	reserved
running_status	string			reserved
last_run	google.protobuf.Timestamp			reserved
next_run	google.protobuf.Timestamp			reserved
num_runs	int64			reserved
execution_failures	JobResponse.ExecutionFailure	repeated	ExecutionFailures is a log of execution failures of the job. It is not guaranteed to contain all execution failures and some execution failures may not contain an error or end.	reserved
coordinator_id	int64		coordinator_id identifies the node coordinating the job. This value will only be present for jobs that are currently running or recently ran.	reserved
messages	JobMessage	repeated		reserved

JobResponse.ExecutionFailure

ExecutionFailure corresponds to a failure to execute the job with the attempt starting at start and ending at end.

Field	Type	Description	Support status
status	string	Status is the status of the job during the execution.	reserved
start	google.protobuf.Timestamp	Start is the time at which the execution started.	reserved
end	google.protobuf.Timestamp	End is the time at which the error occurred.	reserved
error	string	Error is the error which occurred.	reserved

JobMessage

Field	Type	Support status
kind	string	reserved
timestamp	google.protobuf.Timestamp	reserved
message	string	reserved

Job

GET /_admin/v1/jobs/{job_id}

Job returns the job record for the job of the given job_id.

Support status: reserved

Request Parameters

JobRequest requests system job information for the given job_id.

Field	Type	Label	Description	Support status
job_id	int64			reserved

Response Parameters

JobResponse contains the job record for a job.

Field	Type	Label	Description	Support status
id	int64			reserved
type	string			reserved
description	string			reserved
statement	string			reserved
username	string			reserved
descriptor_ids	uint32	repeated		reserved
status	string			reserved
created	google.protobuf.Timestamp			reserved
started	google.protobuf.Timestamp			reserved
finished	google.protobuf.Timestamp			reserved
modified	google.protobuf.Timestamp			reserved
fraction_completed	float			reserved
error	string			reserved
highwater_timestamp	google.protobuf.Timestamp		highwater_timestamp is the highwater timestamp returned as normal timestamp. This is appropriate for display to humans.	reserved
highwater_decimal	string		highwater_decimal is the highwater timestamp in the proprietary decimal form used by logical timestamps internally. This is appropriate to pass to a "AS OF SYSTEM TIME" SQL statement.	reserved
running_status	string			reserved
last_run	google.protobuf.Timestamp			reserved
next_run	google.protobuf.Timestamp			reserved
num_runs	int64			reserved
execution_failures	JobResponse.ExecutionFailure	repeated	ExecutionFailures is a log of execution failures of the job. It is not guaranteed to contain all execution failures and some execution failures may not contain an error or end.	reserved
coordinator_id	int64		coordinator_id identifies the node coordinating the job. This value will only be present for jobs that are currently running or recently ran.	reserved
messages	JobMessage	repeated		reserved

JobResponse.ExecutionFailure

ExecutionFailure corresponds to a failure to execute the job with the attempt starting at start and ending at end.

Field	Type	Description	Support status
status	string	Status is the status of the job during the execution.	reserved
start	google.protobuf.Timestamp	Start is the time at which the execution started.	reserved
end	google.protobuf.Timestamp	End is the time at which the error occurred.	reserved
error	string	Error is the error which occurred.	reserved

JobMessage

Field	Type	Support status
kind	string	reserved
timestamp	google.protobuf.Timestamp	reserved
message	string	reserved

Locations

GET /_admin/v1/locations

Locations returns the locality location records.

Support status: reserved

Request Parameters

LocationsRequest requests system locality location information.

Response Parameters

JobsResponse contains the job record for each matching job.

Field	Type	Label	Description	Support status
locations	LocationsResponse.Location	repeated		reserved

LocationsResponse.Location

Field	Type	Support status
locality_key	string	reserved
locality_value	string	reserved
latitude	double	reserved
longitude	double	reserved

QueryPlan

GET /_admin/v1/queryplan

QueryPlan returns the query plans for a SQL string.

Support status: reserved

Request Parameters

QueryPlanRequest requests the query plans for a SQL string.

Field	Type	Label	Description	Support status
query	string		query is the SQL query string.	reserved

Response Parameters

QueryPlanResponse contains the query plans for a SQL string (currently only the distsql physical query plan).

Field	Type	Label	Description	Support status
distsql_physical_query_plan	string			reserved

Drain

Drain puts the node into the specified drain mode(s) and optionally instructs the process to terminate. We do not expose this via HTTP unless we have a way to authenticate

authorize streaming RPC connections. See #42567.

Support status: reserved

Request Parameters

DrainRequest instructs the receiving node to drain.

Field	Type	Description	Support status
shutdown	bool	When true, terminates the process after the server has started draining. Setting both shutdown and do_drain to false causes the request to only operate as a probe. Setting do_drain to false and shutdown to true causes the server to shut down immediately without first draining.	reserved
do_drain	bool	When true, perform the drain phase. See the comment above on shutdown for an explanation of the interaction between the two. do_drain is also implied by a non-nil deprecated_probe_indicator.	reserved
node_id	string	node_id is a string so that "local" can be used to specify that no forwarding is necessary. For compatibility with v21.2 nodes, an empty node_id is interpreted as "local". This behavior might be removed in subsequent versions.	reserved
verbose	bool	When true, more detailed information is logged during the range lease drain phase.	reserved

Response Parameters

DrainResponse is the response to a successful DrainRequest.

Field	Type	Label	Description	Support status
is_draining	bool		is_draining is set to true iff the server is currently draining. This is set to true in response to a request where skip_drain is false; but it can also be set to true in response to a probe request (!shutdown && skip_drain) if another drain request has been issued prior or asynchronously.	reserved
drain_remaining_indicator	uint64		drain_remaining_indicator measures, at the time of starting to process the corresponding drain request, how many actions to fully drain the node were deemed to be necessary. Some, but not all, of these actions may already have been carried out by the time this indicator is received by the client. The client should issue requests until this indicator first reaches zero, which indicates that the node is fully drained.

The API contract is the following:

upon a first Drain call with do_drain set, the remaining indicator will have some value >=0. If >0, it indicates that drain is pushing state away from the node. (What this state precisely means is left unspecified for this field. See below for details.)
upon a subsequent Drain call with do_drain set, the remaining indicator should have reduced in value. The drain process does best effort at shedding state away from the node; hopefully, all the state is shed away upon the first call and the progress indicator can be zero as early as the second call. However, if there was a lot of state to shed, it is possible for timeout to be encountered upon the first call. In that case, the second call will do some more work and return a non-zero value as well.
eventually, in an iterated sequence of DrainRequests with do_drain set, the remaining indicator should reduce to zero. At that point the client can conclude that no state is left to shed, and it should be safe to shut down the node with a DrainRequest with shutdown = true.

Note that this field is left unpopulated (and thus remains at zero) for pre-20.1 nodes. A client can recognize this by observing is_draining to be false after a request with do_drain = true: the is_draining field is also left unpopulated by pre-20.1 nodes. | reserved | | drain_remaining_description | string | | drain_remaining_description is an informal (= not machine-parsable) string that explains the progress of the drain process to human eyes. This is intended for use mainly for troubleshooting.

The field is only populated if do_drain is true in the request. | reserved |

DecommissionPreCheck

DecommissionPreCheck requests that the server execute preliminary checks to evaluate the possibility of successfully decommissioning a given node.

Support status: reserved

Request Parameters

DecommissionPreCheckRequest requests that preliminary checks be run to ensure that the specified node(s) can be decommissioned successfully.

Field	Type	Label	Description	Support status
node_ids	int32	repeated		reserved
num_replica_report	int32		The maximum number of ranges for which to report errors.	reserved
strict_readiness	bool		If true, all ranges on the checked nodes must only need replacement or removal for decommissioning.	reserved
collect_traces	bool		If true, collect traces for each range checked. Requires num_replica_report > 0.	reserved

Response Parameters

DecommissionPreCheckResponse returns the number of replicas that encountered errors when running preliminary decommissioning checks, as well as the associated error messages and traces, for each node.

Field	Type	Label	Description	Support status
checked_nodes	DecommissionPreCheckResponse.NodeCheckResult	repeated	Status of the preliminary decommission checks across nodes.	reserved

DecommissionPreCheckResponse.NodeCheckResult

The result of checking a single node's readiness for decommission.

Field	Type	Label	Description	Support status
node_id	int32			reserved
decommission_readiness	DecommissionPreCheckResponse.NodeReadiness		The node's decommission readiness status.	reserved
replica_count	int64		The number of total replicas on the node, computed by scanning range descriptors.	reserved
checked_ranges	DecommissionPreCheckResponse.RangeCheckResult	repeated	The details and recorded traces from preprocessing each range with a replica on the checked nodes that resulted in error, up to the maximum specified in the request.	reserved

DecommissionPreCheckResponse.RangeCheckResult

The result of checking a range's readiness for the decommission.

Field	Type	Label	Description	Support status
range_id	int32			reserved
action	string		The action determined by the allocator that is needed for the range.	reserved
events	TraceEvent	repeated	All trace events collected while checking the range.	reserved
error	string		The error message from the allocator's processing, if any.	reserved

TraceEvent

Field	Type	Label	Description	Support status
time	google.protobuf.Timestamp			reserved
message	string			reserved

Decommission

Decommission puts the node(s) into the specified decommissioning state. If this ever becomes exposed via HTTP, ensure that it performs authorization. See #42567.

Support status: reserved

Request Parameters

DecommissionRequest requests the server to set the membership status on all nodes specified by NodeIDs to the value of TargetMembership.

If no NodeIDs are given, it targets the recipient node.

Field	Type	Label	Description	Support status
node_ids	int32	repeated		reserved
target_membership	cockroach.kv.kvserver.liveness.livenesspb.MembershipStatus			reserved
num_replica_report	int32		The number of decommissioning replicas to be reported.	reserved

Response Parameters

DecommissionStatusResponse lists decommissioning statuses for a number of NodeIDs.

Field	Type	Label	Description	Support status
status	DecommissionStatusResponse.Status	repeated	Status of all affected nodes.	reserved

DecommissionStatusResponse.Status

Field	Type	Label	Description	Support status
node_id	int32			reserved
is_live	bool			reserved
replica_count	int64		The number of replicas on the node, computed by scanning meta2 ranges.	reserved
membership	cockroach.kv.kvserver.liveness.livenesspb.MembershipStatus		The membership status of the given node.	reserved
draining	bool			reserved
reported_replicas	DecommissionStatusResponse.Replica	repeated	Decommissioning replicas on the given node to be reported. How many replicas are reported is determined by what was specified in the request.	reserved

DecommissionStatusResponse.Replica

Field	Type	Label	Description	Support status
replica_id	int32			reserved
range_id	int32			reserved

DecommissionStatus

DecommissionStatus retrieves the decommissioning status of the specified nodes. If this ever becomes exposed via HTTP, ensure that it performs authorization. See #42567.

Support status: reserved

Request Parameters

DecommissionStatusRequest requests the decommissioning status for the specified or, if none are specified, all nodes.

Field	Type	Label	Description	Support status
node_ids	int32	repeated		reserved
num_replica_report	int32		The number of decommissioning replicas to be reported.	reserved

Response Parameters

DecommissionStatusResponse lists decommissioning statuses for a number of NodeIDs.

Field	Type	Label	Description	Support status
status	DecommissionStatusResponse.Status	repeated	Status of all affected nodes.	reserved

DecommissionStatusResponse.Status

Field	Type	Label	Description	Support status
node_id	int32			reserved
is_live	bool			reserved
replica_count	int64		The number of replicas on the node, computed by scanning meta2 ranges.	reserved
membership	cockroach.kv.kvserver.liveness.livenesspb.MembershipStatus		The membership status of the given node.	reserved
draining	bool			reserved
reported_replicas	DecommissionStatusResponse.Replica	repeated	Decommissioning replicas on the given node to be reported. How many replicas are reported is determined by what was specified in the request.	reserved

DecommissionStatusResponse.Replica

Field	Type	Label	Description	Support status
replica_id	int32			reserved
range_id	int32			reserved

RangeLog

GET /_admin/v1/rangelog/{range_id}

URL: /_admin/v1/rangelog URL: /_admin/v1/rangelog?limit=100 URL: /_admin/v1/rangelog/1 URL: /_admin/v1/rangelog/1?limit=100

Support status: reserved

Request Parameters

RangeLogRequest request the history of a range from the range log.

Field	Type	Label	Description	Support status
range_id	int64		TODO(tamird): use [(gogoproto.customname) = "RangeID"] below. Need to figure out how to teach grpc-gateway about custom names. If RangeID is 0, returns range log history without filtering by range.	reserved
limit	int32		limit is the total number of results that are retrieved by the query. If this is omitted or set to 0, the default maximum number of results are returned. When set to > 0, at most only that number of results are returned. When set to < 0, an unlimited number of results are returned.	reserved

Response Parameters

RangeLogResponse contains a list of entries from the range log table.

Field	Type	Label	Description	Support status
events	RangeLogResponse.Event	repeated		reserved

RangeLogResponse.Event

Field	Type	Label	Description	Support status
event	cockroach.kv.kvserver.storagepb.RangeLogEvent			reserved
pretty_info	RangeLogResponse.PrettyInfo			reserved

RangeLogResponse.PrettyInfo

To avoid porting the pretty printing of keys and descriptors to javascript, they will be precomputed on the serverside.

Field	Type	Support status
updated_desc	string	reserved
new_desc	string	reserved
added_replica	string	reserved
removed_replica	string	reserved
reason	string	reserved
details	string	reserved

DataDistribution

GET /_admin/v1/data_distribution

Support status: reserved

Request Parameters

Response Parameters

Field	Type	Label	Description	Support status
database_info	DataDistributionResponse.DatabaseInfoEntry	repeated	By database name.	reserved
zone_configs	DataDistributionResponse.ZoneConfigsEntry	repeated	By zone name.	reserved

DataDistributionResponse.DatabaseInfoEntry

Field	Type	Label	Description	Support status
key	string
value	DataDistributionResponse.DatabaseInfo

DataDistributionResponse.DatabaseInfo

Field	Type	Label	Description	Support status
table_info	DataDistributionResponse.DatabaseInfo.TableInfoEntry	repeated	By table name.	reserved

DataDistributionResponse.DatabaseInfo.TableInfoEntry

Field	Type	Label	Description	Support status
key	string
value	DataDistributionResponse.TableInfo

DataDistributionResponse.TableInfo

Field	Type	Label	Description	Support status
replica_count_by_node_id	DataDistributionResponse.TableInfo.ReplicaCountByNodeIdEntry	repeated		reserved
dropped_at	google.protobuf.Timestamp			reserved

DataDistributionResponse.TableInfo.ReplicaCountByNodeIdEntry

Field	Type	Label	Description	Support status
key	int32
value	int64

DataDistributionResponse.ZoneConfigsEntry

Field	Type	Label	Description	Support status
key	string
value	DataDistributionResponse.ZoneConfig

DataDistributionResponse.ZoneConfig

Field	Type	Description	Support status
target	string	target is the object the zone config applies to, e.g. "DATABASE db" or "PARTITION north_america OF TABLE users".	reserved
config	cockroach.config.zonepb.ZoneConfig		reserved
config_sql	string	config_sql is the SQL representation of config.	reserved

AllMetricMetadata

GET /_admin/v1/metricmetadata

URL: /_admin/v1/metricmetadata

Support status: reserved

Request Parameters

MetricMetadataRequest requests metadata for all metrics.

Response Parameters

MetricMetadataResponse contains the metadata for all metrics.

Field	Type	Label	Description	Support status
metadata	MetricMetadataResponse.MetadataEntry	repeated		reserved
recordedNames	MetricMetadataResponse.RecordedNamesEntry	repeated	Maps of metric metadata names to the tsdb recorded metric names	reserved

MetricMetadataResponse.MetadataEntry

Field	Type	Label	Description	Support status
key	string
value	cockroach.util.metric.Metadata

MetricMetadataResponse.RecordedNamesEntry

Field	Type	Label	Description	Support status
key	string
value	string

ChartCatalog

GET /_admin/v1/chartcatalog

URL: /_admin/v1/chartcatalog

Support status: reserved

Request Parameters

ChartCatalogRequest requests returns a catalog of Admin UI charts.

Response Parameters

ChartCatalogResponse returns a catalog of Admin UI charts useful for debugging.

Field	Type	Label	Description	Support status
catalog	cockroach.ts.catalog.ChartSection	repeated		reserved

EnqueueRange

POST /_admin/v1/enqueue_range

EnqueueRange runs the specified range through the specified queue on the range's leaseholder store, returning the detailed trace and error information from doing so. Parameters must be provided in the body of the POST request. For example:

{ "queue": "raftlog", "rangeId": 10 }

Support status: reserved

Request Parameters

Field	Type	Description	Support status
node_id	int32	The node on which the queue should process the range. If node_id is 0, the request will be forwarded to all other nodes.	reserved
queue	string	The name of the replica queue to run the range through. Matched against each queue's name field. See the implementation of baseQueue for details.	reserved
range_id	int32	The ID of the range to run through the queue.	reserved
skip_should_queue	bool	If set, run the queue's process method without first checking whether the replica should be processed by calling shouldQueue.	reserved

Response Parameters

Field	Type	Label	Description	Support status
details	EnqueueRangeResponse.Details	repeated		reserved

EnqueueRangeResponse.Details

Field	Type	Label	Description	Support status
node_id	int32			reserved
events	TraceEvent	repeated	All trace events collected while processing the range in the queue.	reserved
error	string		The error message from the queue's processing, if any.	reserved

TraceEvent

Field	Type	Label	Description	Support status
time	google.protobuf.Timestamp			reserved
message	string			reserved

SendKVBatch

SendKVBatch proxies the given BatchRequest into KV, returning the response. It is used by the CLI debug send-kv-batch command.

Support status: reserved

Request Parameters

Response Parameters

ListTracingSnapshots

GET /_admin/v1/trace_snapshots

ListTracingSnapshots retrieves the list of snapshots of the Active Spans Registry that the node currently has in memory. A new snapshot can be captured with TakeTracingSnapshots.

Support status: reserved

Request Parameters

Response Parameters

Field	Type	Label	Description	Support status
snapshots	SnapshotInfo	repeated		reserved

SnapshotInfo

Field	Type	Label	Description	Support status
snapshot_id	int64		SnapshotID identifies a specific snapshot which can be requested via a GetTracingSnapshotRequest. Negative IDs are used for "automatic" snapshots.	reserved
captured_at	google.protobuf.Timestamp			reserved

TakeTracingSnapshot

POST /_admin/v1/trace_snapshots

TakeTracingSnapshot captures a new snapshot of the Active Spans Registry. The new snapshot is returned, and also made available through ListTracingSnapshots.

Support status: reserved

Request Parameters

Response Parameters

Field	Type	Label	Description	Support status
snapshot	SnapshotInfo			reserved

SnapshotInfo

Field	Type	Label	Description	Support status
snapshot_id	int64		SnapshotID identifies a specific snapshot which can be requested via a GetTracingSnapshotRequest. Negative IDs are used for "automatic" snapshots.	reserved
captured_at	google.protobuf.Timestamp			reserved

GetTracingSnapshot

GET /_admin/v1/trace_snapshots/{snapshot_id}

GetTracingSnapshot returns a snapshot of the tracing spans in the active spans registry previously generated through TakeTracingSnapshots.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
snapshot_id	int64		SnapshotId indicates which snapshot is requested. ID may be negative when requesting an "automatic" snapshot; see ListTracingSnapshotsResponse.	reserved

Response Parameters

Field	Type	Label	Description	Support status
snapshot	TracingSnapshot			reserved

TracingSnapshot

TracingSnapshot represents a snapshot of the active spans registry, including all the spans that were open at the time when the snapshot was taken.

Field	Type	Label	Description	Support status
snapshot_id	int64			reserved
captured_at	google.protobuf.Timestamp			reserved
spans	TracingSpan	repeated		reserved
stacks	TracingSnapshot.StacksEntry	repeated	Ideally we'd use int64 to match the goroutine_id type but unfortunately, the way that grpc-gateway parses these objects into Javascript results in odd encodings of Long JS types that are difficult to interact with as map keys. Thus, we settle for string.	reserved

TracingSpan

TracingSpan represents a span, in a form slightly processed for the use of the tracing UI.

Field	Type	Label	Description	Support status
operation	string			reserved
trace_id	uint64			reserved
span_id	uint64			reserved
parent_span_id	uint64			reserved
start	google.protobuf.Timestamp			reserved
goroutine_id	uint64			reserved
processed_tags	SpanTag	repeated		reserved
current	bool		current is set if the span is still alive (i.e. still present in the active spans registry).	reserved
current_recording_mode	cockroach.util.tracing.tracingpb.RecordingMode		current_recording_mode represents the span's current recording mode. This is not set if current == false.	reserved
children_metadata	NamedOperationMetadata	repeated		reserved

SpanTag

SpanTag represents a tag on a tracing span, in a form processed for the use of the tracing UI.

Field	Type	Label	Description	Support status
key	string			reserved
val	string			reserved
caption	string			reserved
link	string			reserved
hidden	bool			reserved
highlight	bool			reserved
inherit	bool			reserved
inherited	bool			reserved
propagate_up	bool			reserved
copied_from_child	bool			reserved
children	ChildSpanTag	repeated	May be empty.	reserved

ChildSpanTag

Field	Type	Label	Description	Support status
key	string			reserved
val	string			reserved

NamedOperationMetadata

Field	Type	Label	Description	Support status
name	string			reserved
metadata	cockroach.util.tracing.tracingpb.OperationMetadata			reserved

TracingSnapshot.StacksEntry

Field	Type	Label	Description	Support status
key	string
value	string

GetTrace

POST /_admin/v1/traces

GetTrace returns the trace with a specified ID. Depending on the request, the trace is returned either from a snapshot that was previously taken, or directly from the active spans registry.

Support status: reserved

Request Parameters

GetTrace represents the request of the GetTrace RPC.

Field	Type	Description	Support status
snapshot_id	int64	If a snapshot is specified, the trace information is returned from that snapshot. If a snapshot is not specified, information about currently opened spans is returned from the active spans registry.	reserved
trace_id	uint64		reserved
recording_type	cockroach.util.tracing.tracingpb.RecordingMode		reserved

Response Parameters

GetTrace represents the response to the GetTrace RPC.

Field	Type	Description	Support status
snapshot_id	int64	snapshot_id identifies the snapshot that the trace was retrieved from. If 0, the trace was not retrieved from a registry, but directly from the active spans registry.	reserved
trace_id	uint64		reserved
still_exists	bool	still_exists is set if any spans from this trace are currently present in the active spans registry.

If snapshot_id is 0, still_exists is always set. | reserved | | serialized_recording | string | | serialized_recording represents the serialization of trace recording. We return the recording already serialized as formatted string for easy consumption in the browser. | reserved |

SetTraceRecordingType

POST /_admin/v1/settracerecordingtype

SetTraceRecordingType sets the recording mode of all or some of the spans in a trace.

Support status: reserved

Request Parameters

SetTraceRecordingTypeRequest is the request for SetTraceRecordingType, which sets the recording mode of all or some of the spans in a trace.

Field	Type	Description	Support status
trace_id	uint64	TraceID identifies the trace to toggle the recording of. It must always be specified.	reserved
span_id	uint64	SpanID, if not zero, controls which spans in the trace get their recording mode set. If zero, all spans in the trace are updated. If not zero, only the respective span and its descendants get updated.	reserved
recording_mode	cockroach.util.tracing.tracingpb.RecordingMode		reserved

Response Parameters

SetTraceRecordingTypeRequest is the response for SetTraceRecordingType.

RecoveryCollectReplicaInfo

RecoveryCollectReplicaInfo retrieves information about:

range descriptors contained in cluster meta ranges if meta ranges are readable;
replica information from all live nodes that have connection to the target node.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
max_concurrency	int32		MaxConcurrency is the maximum parallelism that will be used when fanning out RPCs to nodes in the cluster while servicing this request. A value of 0 disables concurrency. A negative value configures no limit for concurrency.	reserved

Response Parameters

Field	Type	Support status
range_descriptor	cockroach.roachpb.RangeDescriptor	reserved
replica_info	cockroach.kv.kvserver.loqrecovery.loqrecoverypb.ReplicaInfo	reserved
node_stream_restarted	RecoveryCollectReplicaRestartNodeStream	reserved
metadata	cockroach.kv.kvserver.loqrecovery.loqrecoverypb.ClusterMetadata	reserved

RecoveryCollectReplicaRestartNodeStream

RecoveryCollectReplicaRestartNodeStream is sent by collector node to client if it experiences a transient failure collecting data from one of the nodes. This message instructs client to drop any data that it collected locally for specified node as streaming for this node would be restarted. This mechanism is needed to avoid restarting the whole collection procedure in large cluster if one of the nodes fails transiently.

Field	Type	Label	Description	Support status
node_id	int32			reserved

RecoveryCollectLocalReplicaInfo

RecoveryCollectLocalReplicaInfo retrieve information about all local replicas in all stores on the node.

Support status: reserved

Request Parameters

Response Parameters

Field	Type	Label	Description	Support status
replica_info	cockroach.kv.kvserver.loqrecovery.loqrecoverypb.ReplicaInfo			reserved

RecoveryStagePlan

RecoveryStagePlan stages recovery plan on target or all nodes in cluster depending on request content and marks nodes deleted in the plan as decommissioned in each node's local node tombstone storage.

Support status: reserved

Request Parameters

Field	Type	Description	Support status
plan	cockroach.kv.kvserver.loqrecovery.loqrecoverypb.ReplicaUpdatePlan	Plan is replica update plan to stage for application on next restart. Plan could be empty in that case existing plan is removed if present.	reserved
all_nodes	bool	If all nodes is true, then receiver should act as a coordinator and perform a fan-out to stage plan on all nodes of the cluster.	reserved
force_plan	bool	ForcePlan tells receiver to ignore any plan already staged on the node if it is present and replace it with new plan (including empty one).	reserved
force_local_internal_version	bool	ForceLocalInternalVersion tells server to update internal component of plan version to the one of active cluster version. This option needs to be set if target cluster is stuck in recovery where only part of nodes were successfully migrated.	reserved
max_concurrency	int32	MaxConcurrency is the maximum parallelism that will be used when fanning out RPCs to nodes in the cluster while servicing this request. A value of 0 disables concurrency. A negative value configures no limit for concurrency.	reserved

Response Parameters

Field	Type	Label	Description	Support status
errors	string	repeated	Errors contain error messages happened during plan staging.	reserved

RecoveryNodeStatus

RecoveryNodeStatus retrieves loss of quorum recovery status of a single node.

Support status: reserved

Request Parameters

Response Parameters

Field	Type	Label	Description	Support status
status	cockroach.kv.kvserver.loqrecovery.loqrecoverypb.NodeRecoveryStatus			reserved

RecoveryVerify

RecoveryVerify verifies that recovery plan is applied on all necessary nodes, ranges are available and nodes removed in plan are marked as decommissioned.

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
plan_id	bytes		PlanID is ID of the plan to verify.	reserved
decommissioned_node_ids	int32	repeated	DecommissionedNodeIDs is a set of nodes that should be marked as decommissioned in the cluster when loss of quorum recovery successfully applies.	reserved
max_reported_ranges	int32		MaxReportedRanges is the maximum number of failed ranges to report. If more unhealthy ranges are found, error will be returned alongside range to indicate that ranges were cut short.	reserved
max_concurrency	int32		MaxConcurrency is the maximum parallelism that will be used when fanning out RPCs to nodes in the cluster while servicing this request. A value of 0 disables concurrency. A negative value configures no limit for concurrency.	reserved

Response Parameters

Field	Type	Label	Description	Support status
statuses	cockroach.kv.kvserver.loqrecovery.loqrecoverypb.NodeRecoveryStatus	repeated	Statuses contain a list of recovery statuses of nodes updated during recovery. It also contains nodes that were expected to be live (not decommissioned by recovery) but failed to return status response.	reserved
unavailable_ranges	RecoveryVerifyResponse.UnavailableRanges		UnavailableRanges contains information about ranges that failed health check.	reserved
decommissioned_node_statuses	RecoveryVerifyResponse.DecommissionedNodeStatusesEntry	repeated	DecommissionedNodeStatuses contains a map of requested IDs with their corresponding liveness statuses.	reserved

RecoveryVerifyResponse.UnavailableRanges

Field	Type	Label	Description	Support status
ranges	cockroach.kv.kvserver.loqrecovery.loqrecoverypb.RangeRecoveryStatus	repeated	Ranges contains descriptors of ranges that failed health check. If there are too many ranges to report, error would contain relevant message.	reserved
error	string		Error contains an optional error if ranges validation can't complete.	reserved

RecoveryVerifyResponse.DecommissionedNodeStatusesEntry

Field	Type	Label	Description	Support status
key	int32
value	cockroach.kv.kvserver.liveness.livenesspb.MembershipStatus

ListTenants

GET /_admin/v1/tenants

ListTenants returns a list of active tenants in the cluster.

Support status: reserved

Request Parameters

Response Parameters

Field	Type	Label	Description	Support status
tenants	Tenant	repeated		reserved

Tenant

Field	Type	Support status
tenant_id	cockroach.roachpb.TenantID	reserved
tenant_name	string	reserved
sql_addr	string	reserved
rpc_addr	string	reserved

ReadFromTenantInfo

ReadFromTenantInfo returns the tenant from which the requesting tenant should read, if any.

Support status: reserved

Request Parameters

ReadFromTenantInfoRequest requests info, if any, on which tenant the caller should read from.

Field	Type	Label	Description	Support status
tenant_id	cockroach.roachpb.TenantID		TenantID should always be the ID of the tenant making the request. This duplicates the ID in the auth context that is added implicitly, and must always match that ID when that ID is present, however that ID is absent in insecure test clusters which is why we also specify it explicitly here.	reserved

Response Parameters

ReadFromTenantInfoResponse instructs a tenant as to which tenant, if any, it should configure itself to read from and the timestamp at which it should do so.

Field	Type	Label	Description	Support status
read_from	cockroach.roachpb.TenantID			reserved
read_at	cockroach.util.hlc.Timestamp			reserved