> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# DB Console Overview

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

The DB Console provides details about your cluster and database configuration, and helps you optimize cluster performance.

<Note>
  Authorized CockroachDB Advanced cluster users can visit the DB Console at a URL provisioned for the cluster.
</Note>

Refer to: <InternalLink version="cockroachcloud" path="network-authorization#db-console">Network Authorization for CockroachDB Cloud Clusters—DB Console</InternalLink>

## Authentication

The DB Console supports username/password login and single sign-on (SSO) for Advanced and Enterprise clusters.

The DB Console sign-on page can also be used to provision authentication tokens for SQL client access.

Refer to:

* <InternalLink path="sso-db-console">Single Sign-on (SSO) for DB Console</InternalLink>
* <InternalLink path="sso-sql">Cluster Single Sign-on (SSO) using JSON web tokens (JWTs)</InternalLink>

## DB Console areas

### Overview

The Overview page provides a cluster overview and node list and map.

* <InternalLink path="ui-cluster-overview-page">Cluster Overview</InternalLink> has essential metrics about the cluster and nodes, including liveness status, replication status, uptime, and hardware usage.
* <InternalLink path="ui-cluster-overview-page#node-map">Node List</InternalLink> has a list of cluster metrics at the locality and node levels.
* <InternalLink path="ui-cluster-overview-page#node-map">Node Map</InternalLink> displays a geographical configuration of your cluster and metrics at the locality and node levels, visualized on a map.

### Metrics

The Metrics page provides dashboards for all types of CockroachDB metrics.

* <InternalLink path="ui-overview-dashboard">Overview dashboard</InternalLink> has metrics about SQL performance, replication, and storage.
* <InternalLink path="ui-hardware-dashboard">Hardware dashboard</InternalLink> has metrics about CPU usage, disk throughput, network traffic, storage capacity, and memory.
* <InternalLink path="ui-runtime-dashboard">Runtime dashboard</InternalLink> has metrics about node count, CPU time, and memory usage.
* <InternalLink path="ui-sql-dashboard">SQL dashboard</InternalLink> has metrics about SQL connections, byte traffic, queries, transactions, and service latency.
* <InternalLink path="ui-storage-dashboard">Storage dashboard</InternalLink> has metrics about storage capacity and file descriptors.
* <InternalLink path="ui-replication-dashboard">Replication dashboard</InternalLink> has metrics about how data is replicated across the cluster, e.g., range status, replicas per store, etc.
* <InternalLink path="ui-distributed-dashboard">Distributed dashboard</InternalLink> has metrics about distribution tasks across the cluster, including RPCs and transactions.
* <InternalLink path="ui-queues-dashboard">Queues dashboard</InternalLink> has metrics about the health and performance of various queueing systems in CockroachDB, including the garbage collection and Raft log queues.
* <InternalLink path="ui-slow-requests-dashboard">Slow requests dashboard</InternalLink> has metrics about important cluster tasks that take longer than expected to complete, including Raft proposals and lease acquisitions.
* <InternalLink path="ui-cdc-dashboard">Changefeeds dashboard</InternalLink> has metrics about the <InternalLink path="change-data-capture-overview">changefeeds</InternalLink> created across your cluster.
* <InternalLink path="ui-overload-dashboard">Overload dashboard</InternalLink> has metrics about the performance of the parts of your cluster relevant to the cluster's <InternalLink path="admission-control">admission control system</InternalLink>.
* <InternalLink path="ui-ttl-dashboard">TTL dashboard</InternalLink> has metrics about the progress and performance of <InternalLink path="row-level-ttl">batch deleting expired data using Row-Level TTL</InternalLink> from your cluster.
* <InternalLink path="ui-physical-cluster-replication-dashboard">Physical Cluster Replication dashboard</InternalLink> has metrics about the <InternalLink path="physical-cluster-replication-overview">physical cluster replication</InternalLink> streams between a primary and standby cluster.

### Databases

The <InternalLink path="ui-databases-page">Databases</InternalLink> page shows details about the system and user databases in the cluster.

### SQL Activity

The **SQL Activity** page summarizes SQL activity in your cluster.

* <InternalLink path="ui-statements-page">**Statements**</InternalLink> shows frequently executed and high-latency <InternalLink path="sql-statements">SQL statements</InternalLink> with the option to collect statement <InternalLink path="ui-statements-page#diagnostics">diagnostics</InternalLink>.
* <InternalLink path="ui-transactions-page">**Transactions**</InternalLink> shows details about transactions running on the cluster.
* <InternalLink path="ui-sessions-page">**Sessions**</InternalLink> shows details about open sessions in the cluster.

### Insights

The <InternalLink path="ui-insights-page">**Insights**</InternalLink> page exposes problematic health signals and enables you to quickly find optimization opportunities to maximize database efficiency. The **Insights** page contains workload-level and schema-level insights.

### Network Latency

The <InternalLink path="ui-network-latency-page">Network Latency</InternalLink> page shows latencies and lost connections between all nodes in your cluster.

### Jobs

The <InternalLink path="ui-jobs-page">Jobs</InternalLink> page shows details of jobs running in the cluster.

### Advanced Debug

The <InternalLink path="ui-debug-pages">Advanced Debug</InternalLink> page provides advanced monitoring and troubleshooting reports. These include details about data distribution, the state of specific queues, and slow query metrics. These details are largely intended for use by CockroachDB developers. To access the **Advanced Debug** page, the user must be a member of the `admin` role or must have the `VIEWDEBUG` <InternalLink path="security-reference/authorization#supported-privileges">system privilege</InternalLink> defined.

## DB Console access

You can access the DB Console from every node at `http://<host:<http-port`, or `http://<host:8080` by default.

* If you included the <InternalLink path="cockroach-start#networking">`--http-addr`</InternalLink> flag when starting nodes, use the IP address or hostname and port specified by that flag.
* If you didn't include the <InternalLink path="cockroach-start#networking">`--http-addr`</InternalLink> flag when starting nodes, use the IP address or hostname specified by the <InternalLink path="cockroach-start#networking">`--listen-addr`</InternalLink> flag and port `8080`.
* If you are running a [secure cluster](#cluster-security), use `https` instead of `http`.

For guidance on accessing the DB Console in the context of cluster deployment, see <InternalLink path="start-a-local-cluster">Start a Local Cluster</InternalLink> and <InternalLink path="manual-deployment">Manual Deployment</InternalLink>.

<Danger>
  Accessing the DB Console for a secure cluster requires login information (i.e., username and password). This login information is stored in a system table that is replicated like other data in the cluster. If a majority of the nodes with the replicas of the system table data go down, users will be locked out of the DB Console.
</Danger>

### Proxy DB Console

If your CockroachDB cluster is behind a load balancer, you may wish to proxy your DB Console connection to a different node in the cluster from the node you first connect to. This is useful in deployments where a third-party load balancer otherwise determines which CockroachDB node you connect to in DB Console, or where web management access is limited to a subset of CockroachDB instances in a cluster.

You can accomplish this using one of these methods:

* Once connected to DB Console, use the **Web server** dropdown menu from the <InternalLink path="ui-debug-pages#license-and-node-information">**Advanced Debug**</InternalLink> page to select a different node to proxy to.
* Use the `remote_node_id` parameter in your DB Console URL to proxy directly to a specific node. For example, use `http://<host:<http-port/?remote_node_id=2` to proxy directly to node `2`.

## DB Console security considerations

Access to DB Console is a function of cluster security and the privileges of the accessing user.

### Cluster security

On insecure clusters, all areas of the DB Console are accessible to all users.

On secure clusters, for each user who should have access to the DB Console, you must <InternalLink path="create-user#create-a-user-with-a-password">create a user with a password</InternalLink> and optionally <InternalLink path="grant#grant-system-level-privileges-on-the-entire-cluster">`GRANT`</InternalLink> the user <InternalLink path="security-reference/authorization#supported-privileges">system-level privileges</InternalLink> or membership to the <InternalLink path="security-reference/authorization#admin-role">`admin` role</InternalLink>.

### Role-based security

All users have access to data over which they have privileges (e.g., <InternalLink path="ui-jobs-page">jobs</InternalLink> and <InternalLink path="ui-sessions-page">list of sessions</InternalLink>), and data that does not require privileges (e.g., <InternalLink path="ui-cluster-overview-page">cluster health, node status</InternalLink>, <InternalLink path="ui-overview-dashboard">metrics</InternalLink>).

The following areas display information from privileged HTTP endpoints that require the user to have the <InternalLink path="security-reference/authorization#admin-role">`admin` role</InternalLink> or the specified <InternalLink path="security-reference/authorization#supported-privileges">system-level privileges</InternalLink>.

| DB Console area                                                                                                | System-level privilege                                                                                                                                                                   | Privileged information            |
| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| <InternalLink path="ui-statements-page">Statements</InternalLink>                                              | <InternalLink path="security-reference/authorization">`VIEWACTIVITY`</InternalLink> or <InternalLink path="security-reference/authorization">`VIEWACTIVITYREDACTED`</InternalLink>       | SQL statements                    |
| <InternalLink path="ui-transactions-page">Transactions</InternalLink>                                          | <InternalLink path="security-reference/authorization">`VIEWACTIVITY`</InternalLink> or <InternalLink path="security-reference/authorization">`VIEWACTIVITYREDACTED`</InternalLink>       | Transactions                      |
| <InternalLink path="ui-sessions-page">Sessions</InternalLink>                                                  | <InternalLink path="security-reference/authorization">`VIEWACTIVITY`</InternalLink> or <InternalLink path="security-reference/authorization">`VIEWACTIVITYREDACTED`</InternalLink>       | Sessions                          |
| <InternalLink path="ui-insights-page">Insights</InternalLink>                                                  | <InternalLink path="security-reference/authorization">`VIEWACTIVITY`</InternalLink> or <InternalLink path="security-reference/authorization">`VIEWACTIVITYREDACTED`</InternalLink>       | Insights                          |
| <InternalLink path="ui-top-ranges-page">Top Ranges</InternalLink>                                              | <InternalLink path="security-reference/authorization">`VIEWCLUSTERMETADATA`</InternalLink>                                                                                               | Ranges                            |
| <InternalLink path="ui-jobs-page">Jobs</InternalLink>                                                          | <InternalLink path="security-reference/authorization">`VIEWJOB`</InternalLink>                                                                                                           | Jobs                              |
| <InternalLink path="ui-debug-pages">Advanced Debug</InternalLink>                                              | <InternalLink path="security-reference/authorization">`VIEWDEBUG`</InternalLink>                                                                                                         | Debugging and profiling endpoints |
| <InternalLink path="ui-debug-pages#reports">Advanced Debug > Problem Ranges</InternalLink>                     | <InternalLink path="security-reference/authorization">`VIEWCLUSTERMETADATA`</InternalLink>                                                                                               | Ranges                            |
| <InternalLink path="ui-debug-pages#reports">Advanced Debug > Data Distribution and Zone Configs</InternalLink> | <InternalLink path="security-reference/authorization">`VIEWCLUSTERMETADATA`</InternalLink>                                                                                               | Ranges                            |
| <InternalLink path="ui-debug-pages#configuration">Advanced Debug > Cluster Settings</InternalLink>             | <InternalLink path="security-reference/authorization">`VIEWCLUSTERSETTING`</InternalLink> or <InternalLink path="security-reference/authorization">`MODIFYCLUSTERSETTING`</InternalLink> | Cluster Settings                  |

## DB Console timezone configuration

To view timestamps in your preferred timezone in the DB Console, use the <InternalLink path="cluster-settings">`ui.default_timezone` cluster setting</InternalLink>. This setting supports all valid timezone identifiers, such as `America/New_York` and `Asia/Tokyo`.

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SET CLUSTER SETTING ui.default_timezone = 'America/New_York';
```

If no value is set, the DB Console displays timestamps in UTC.

<Note>
  The <InternalLink path="cluster-settings">`ui.display_timezone` cluster setting</InternalLink> is now deprecated and will be removed in a future release. Avoid using `ui.display_timezone`. Use `ui.default_timezone` instead for full support and forward compatibility.
</Note>

## DB Console troubleshooting

The DB Console stores temporary data in a time-series database in order to generate the various [metrics](#metrics) graphs. If your cluster is comprised of a large number of nodes where individual nodes have very limited memory available (e.g., under `8 GiB`), this underlying time-series database may not have enough memory available per-node to serve these requests quickly. If the DB Console experiences issues rendering these metrics graphs, consider increasing the value of the <InternalLink path="cockroach-start">`--max-tsdb-memory`</InternalLink> flag.

## Diagnostics reporting

By default, the DB Console shares anonymous usage details with Cockroach Labs. For information about the details shared and how to opt-out of reporting, see <InternalLink path="diagnostics-reporting">Diagnostics Reporting</InternalLink>.

## License expiration message

If you have <InternalLink path="licensing-faqs#set-a-license">set a license</InternalLink>, a license expiration message is displayed at the top-right of the DB Console. While the license is valid, the message will read `License expires in X days`, where `X` is the number of days. If the license is no longer valid, the message will read `License expired X days ago`. Hovering over either message displays a tooltip with the expiration date of the license.

Depending on the status of your cluster's <InternalLink path="licensing-faqs">license</InternalLink>, the following messages may be displayed in the DB Console:

* If your cluster was throttled because a valid license key was never added, the message is: *This cluster was throttled because it requires a license key. Please add a license key to continue using this cluster.*
* If your cluster has an invalid license key and the cluster is still in the grace period, the message is: *Your license key expired on \${DATE1}. The cluster will be throttled on \${DATE2} unless a new license key is added.*
* If your cluster was throttled due to an invalid license, the message is: *Your license key expired on \${DATE} and the cluster was throttled. Please add a license key to continue using this cluster.*
* If the cluster is required to send telemetry but has not been sending it, and is not yet being throttled, the message is: *Telemetry has not been received from some nodes in this cluster since \${DATE}. These nodes will be throttled on \${DATE} unless telemetry is received.*
* If the cluster is required to send telemetry but has not been sending it, and is currently being throttled, the message is: *Telemetry has not been received from some nodes in this cluster since \${DATE1}. These nodes were throttled on \${DATE2}.*

For instructions on how to obtain and set a license, refer to <InternalLink path="licensing-faqs#obtain-a-license">Obtain a license</InternalLink>.

For more information about throttling and telemetry, refer to <InternalLink path="licensing-faqs">What is throttling and how does it work?</InternalLink>

## See also

* <InternalLink path="troubleshooting-overview">Troubleshooting Overview</InternalLink>
* <InternalLink path="support-resources">Support Resources</InternalLink>
* <InternalLink path="monitoring-and-alerting#raw-status-endpoints">Raw Status Endpoints</InternalLink>