full.md

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
data	bytes		data is the raw file contents of the certificate. This means PEM-encoded DER data.	reserved
fields	CertificateDetails.Fields	repeated		reserved

CertificateDetails.Fields

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

Response Parameters

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

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.

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. Note that this does not report the number of CPUs actually used by cockroach; this parameter is controlled separately.	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
incoming	int64		in bytes	reserved
outgoing	int64		in bytes	reserved
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

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. 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. Note that this does not report the number of CPUs actually used by cockroach; this parameter is controlled separately.	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
incoming	int64		in bytes	reserved
outgoing	int64		in bytes	reserved
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	Description	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
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
latches_local	cockroach.kv.kvserver.storagepb.LatchManagerInfo			reserved
latches_global	cockroach.kv.kvserver.storagepb.LatchManagerInfo			reserved
lease_status	cockroach.kv.kvserver.storagepb.LeaseStatus			reserved
quiescent	bool			reserved
ticking	bool			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/etcd/raft.

Field	Type	Label	Description	Support status
replica_id	uint64			reserved
hard_state	raftpb.HardState			reserved
lead	uint64		Lead is part of Raft's SoftState.	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

RaftState.ProgressEntry

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

RaftState.Progress

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

RangeProblems

Field	Type	Label	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

RangeStatistics

Field	Type	Label	Description	Support status
queries_per_second	double		Note that queries per second will only be known by the leaseholder. All other replicas will report it as 0.	reserved
writes_per_second	double			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

Response Parameters

Field	Type	Label	Description	Support status
ranges	RangeInfo	repeated		reserved

RangeInfo

Field	Type	Label	Description	Support status
span	PrettySpan			reserved
raft_state	RaftState			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
latches_local	cockroach.kv.kvserver.storagepb.LatchManagerInfo			reserved
latches_global	cockroach.kv.kvserver.storagepb.LatchManagerInfo			reserved
lease_status	cockroach.kv.kvserver.storagepb.LeaseStatus			reserved
quiescent	bool			reserved
ticking	bool			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/etcd/raft.

Field	Type	Label	Description	Support status
replica_id	uint64			reserved
hard_state	raftpb.HardState			reserved
lead	uint64		Lead is part of Raft's SoftState.	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

RaftState.ProgressEntry

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

RaftState.Progress

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

RangeProblems

Field	Type	Label	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

RangeStatistics

Field	Type	Label	Description	Support status
queries_per_second	double		Note that queries per second will only be known by the leaseholder. All other replicas will report it as 0.	reserved
writes_per_second	double			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

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	EngineStatsInfo	repeated		reserved

EngineStatsInfo

Field	Type	Label	Description	Support status
store_id	int32			reserved
tickers_and_histograms	cockroach.storage.enginepb.TickersAndHistograms			reserved
engine_type	cockroach.storage.enginepb.EngineType			reserved

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	Label	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

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

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_anon	string		The SQL statement fingerprint of the last query executed on this session, compatible with StatementStatisticsKey.	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			reserved
sql_anon	string		The SQL statement fingerprint, compatible with StatementStatisticsKey.	reserved

TxnInfo

TxnInfo represents an in flight user transaction on some Session.

Field	Type	Label	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

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	Label	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

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

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_anon	string		The SQL statement fingerprint of the last query executed on this session, compatible with StatementStatisticsKey.	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			reserved
sql_anon	string		The SQL statement fingerprint, compatible with StatementStatisticsKey.	reserved

TxnInfo

TxnInfo represents an in flight user transaction on some Session.

Field	Type	Label	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

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 issing 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. node_id is a string so that "local" can be used to specify that no forwarding is necessary.	reserved
query_id	string		ID of query to be canceled (converted to string).	reserved
username	string		Username of the user making this cancellation request. This may be omitted if the user is the same as the one issuing the CancelQueryRequest. The caller is responsible for case-folding and NFC normalization.	reserved

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

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. node_id is a string so that "local" can be used to specify that no forwarding is necessary.	reserved
session_id	bytes			reserved
username	string		Username of the user making this cancellation request. This may be omitted if the user is the same as the one issuing the CancelSessionRequest. The caller is responsiblef or case-folding and NFC normalization.	reserved

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

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

Response Parameters

Field	Type	Label	Description	Support status
range_count	int32			reserved
approximate_disk_bytes	uint64			reserved
total_stats	cockroach.storage.enginepb.MVCCStats			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.	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	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
type	ProfileRequest.Type		The type of profile to retrieve.	reserved
seconds	int32		applies only to Type=CPU, defaults to 30	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.	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	Label	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		reserved

LogFile

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

LogFile retrieves a given log file.

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
file	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

Logs

GET /_status/logs/{node_id}

Logs retrieves individual log entries.

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
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

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	Description	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

HotRanges

GET /_status/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 posssible 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. If left empty, the request is forwarded to every node in the cluster.	alpha

Response Parameters

HotRangesResponse is the payload produced in response to a HotRangesRequest.

Field	Type	Label	Description	Support status
node_id	int32		NodeID is the node that received the HotRangesRequest and forwarded requests to the selected target node(s).	alpha
hot_ranges_by_node_id	HotRangesResponse.HotRangesByNodeIdEntry	repeated	HotRangesByNodeID contains a hot range report for each selected target node ID in the HotRangesRequest.	alpha

HotRangesResponse.HotRangesByNodeIdEntry

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

HotRangesResponse.NodeResponse

NodeResponse is a hot range report for a single target node.

Field	Type	Label	Description	Support status
error_message	string		ErrorMessage is set to a non-empty string if this target node was unable to produce a hot range report. The contents of this string indicates the cause of the failure.	alpha
stores	HotRangesResponse.StoreResponse	repeated	Stores contains the hot ranges report if no error was encountered. There is one part to the report for each store in the target node.	alpha

HotRangesResponse.StoreResponse

StoreResponse contains the part of a hot ranges report that pertains to a single store on a target node.

Field	Type	Label	Description	Support status
store_id	int32		StoreID identifies the store for which the report was produced.	alpha
hot_ranges	HotRangesResponse.HotRange	repeated	HotRanges is the hot ranges report for this store on the target node.	alpha

HotRangesResponse.HotRange

HotRange is a hot range report for a single store on one of the target node(s) selected in a HotRangesRequest.

Field	Type	Label	Description	Support status
desc	cockroach.roachpb.RangeDescriptor		Desc is the descriptor of the range for which the report was produced. TODO(knz): This field should be removed. See: cockroachdb#53212	reserved
queries_per_second	double		QueriesPerSecond is the recent number of queries per second on this range.	alpha

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	Description	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
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
latches_local	cockroach.kv.kvserver.storagepb.LatchManagerInfo			reserved
latches_global	cockroach.kv.kvserver.storagepb.LatchManagerInfo			reserved
lease_status	cockroach.kv.kvserver.storagepb.LeaseStatus			reserved
quiescent	bool			reserved
ticking	bool			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/etcd/raft.

Field	Type	Label	Description	Support status
replica_id	uint64			reserved
hard_state	raftpb.HardState			reserved
lead	uint64		Lead is part of Raft's SoftState.	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

RaftState.ProgressEntry

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

RaftState.Progress

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

RangeProblems

Field	Type	Label	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

RangeStatistics

Field	Type	Label	Description	Support status
queries_per_second	double		Note that queries per second will only be known by the leaseholder. All other replicas will report it as 0.	reserved
writes_per_second	double			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	Label	Description	Support status
store_id	int32			reserved
encryption_status	bytes		encryption_status is a serialized ccl/storageccl/engineccl/enginepbccl/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

Statements

GET /_status/statements

Support status: reserved

Request Parameters

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

StatementsResponse.CollectedStatementStatistics

Field	Type	Label	Description	Support status
key	StatementsResponse.ExtendedStatementStatisticsKey			reserved
id	uint64			reserved
stats	cockroach.sql.StatementStatistics			reserved

StatementsResponse.ExtendedStatementStatisticsKey

Field	Type	Label	Description	Support status
key_data	cockroach.sql.StatementStatisticsKey			reserved
node_id	int32			reserved

StatementsResponse.ExtendedCollectedTransactionStatistics

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

CreateStatementDiagnosticsReport

POST /_status/stmtdiagreports

Support status: reserved

Request Parameters

Field	Type	Label	Description	Support status
statement_fingerprint	string			reserved

Response Parameters

Field	Type	Label	Description	Support status
report	StatementDiagnosticsReport			reserved

StatementDiagnosticsReport

Field	Type	Label	Description	Support status
id	int64			reserved
completed	bool			reserved
statement_fingerprint	string			reserved
statement_diagnostics_id	int64			reserved
requested_at	google.protobuf.Timestamp			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	Label	Description	Support status
id	int64			reserved
completed	bool			reserved
statement_fingerprint	string			reserved
statement_diagnostics_id	int64			reserved
requested_at	google.protobuf.Timestamp			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	Label	Description	Support status
id	int64			reserved
statement_fingerprint	string			reserved
collected_at	google.protobuf.Timestamp			reserved
trace	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

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

Response Parameters

DatabaseDetailsResponse contains grant information and table names 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. It can be used to find events pertaining to this database by filtering on the 'target_id' field of events.	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

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

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 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. It can be used to find events pertaining to this table by filtering on the 'target_id' field of events.	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	Label	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	Label	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 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

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

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

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
• /_admin/v1/events?type=drop_table&target_id=4
• /_admin/v1/events?type=drop_table&target_id=4&limit=100

Support status: reserved

Request Parameters

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

Field	Type	Label	Description	Support status
type	string			reserved
target_id	int64			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	Label	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
target_id	int64		target_id is the target for this event.	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	Label	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 names to retrieve. An empty keys array means "all".	reserved
unredacted_values	bool		Indicate whether to see unredacted setting values. This is opt-in so that a previous version cockroach zip does not start reporting values when this becomes active. For good security, the server only obeys this after it checks that the logger-in user has admin privilege.	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	Label	Description	Support status
value	string			reserved
type	string			reserved
description	string			reserved
public	bool			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	Label	Description	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	JobsResponse.Job	repeated		reserved

JobsResponse.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

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	Label	Description	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	Label	Description	Support status
pre201_marker	int32	repeated	pre_201_marker represents a field that clients stopped using in 20.1. It's maintained to reject requests from such clients, since they're not setting other required fields.	reserved
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

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

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

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

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

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

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	Label	Description	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
zone_config_id	int64			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	Label	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 metics.

Field	Type	Label	Description	Support status
metadata	MetricMetadataResponse.MetadataEntry	repeated		reserved

MetricMetadataResponse.MetadataEntry

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

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	Label	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