Tools Page

The Tools page is accessible on CockroachDB Standard and Advanced clusters. This page allows you to:

• Set up cluster monitoring with Datadog (available on clusters hosted on AWS and GCP).
• Set up cluster monitoring with Amazon CloudWatch (available on clusters hosted on AWS).
• Access the built-in DB Console to view time-series data on SQL queries, troubleshoot query performance, view a list of jobs, and more (available on CockroachDB Advanced clusters).

To view the Tools page, select a cluster from the Clusters page, and click Tools in the Monitoring section of the left side navigation.

Monitor CockroachDB Cloud with Datadog

The CockroachDB Cloud integration for Datadog enables data collection and alerting on a subset of CockroachDB metrics available at the Prometheus endpoint, using the Datadog platform.

To set up Datadog monitoring with CockroachDB Standard and Advanced, your Datadog account must be associated with a Datadog organization.

For more information about using Datadog, see the Datadog documentation.

Enable integration

To enable Datadog monitoring for a CockroachDB Standard or Advanced cluster, you can either:

• Use the Cloud API, following the instructions on Export Metrics From a CockroachDB Standard Cluster or Export Metrics From a CockroachDB Advanced Cluster.

OR

• Use the Cloud Console, following the steps below.

1. On the cluster's Tools page, click Setup in the Datadog panel.

2. Fill in the API key and Datadog Site fields with their corresponding values.

   • The API key is associated with your Datadog organization. If you don't have an API key to use with your CockroachDB Standard or Advanced cluster, you need to create one. For instructions, see the Datadog documentation.
   • Your Datadog Site corresponds to your Datadog Site URL. For more details, see the Datadog documentation.

3. Click Create. Depending on the size of your cluster and the current load on the system, the integration might take some time to become enabled.

4. Once it is registered on Datadog, the cluster will appear on your Datadog Infrastructure List. This can take up to several minutes.

Verify integration status

Once enabled, the Integration status in the Datadog panel on the Tools page will show as Active.

If an issue is encountered during the integration, one of the following statuses may appear instead:

• Active indicates that the integration has been successfully deployed.
• Inactive indicates that the integration has not been successfully deployed. Setup has either not been attempted or has encountered an error.
• Unhealthy indicates that the integration API key is invalid and needs to be updated.
• Unknown indicates that an unknown error has occurred. If this status is displayed, contact our support team.

Metrics export from CockroachDB can be interrupted in the event of:

• A stale API key. In this case, the integration status will be Unhealthy. To resolve the issue, update your integration with a new API key.
• Transient CockroachDB unavailability. In this case, the integration status will continue to be Active but you might experience incomplete metrics exports in Datadog. To resolve the issue, try deactivating and reactivating the integration from the Datadog panel. If this does not resolve the issue, contact our support team.

To monitor the health of metrics export, you can create a custom Monitor in Datadog.

View and configure dashboards

Open your Datadog Dashboard List. There are two sample dashboards that present CockroachDB metrics:

• CockroachDB Cloud Standard (formerly Serverless)
• CockroachDB Cloud Advanced (formerly Dedicated)

Both sample dashboards presents a high-level view of SQL performance and latency, and information about resource consumption to help aid in capacity planning. CockroachDB Cloud Advanced provides the ability to drill down to specific nodes (identified by a (node, region) tag pair) within your cluster.

To create your own CockroachDB Standard or Advanced dashboard, you can either clone the default dashboards and edit the widgets, or create a new dashboard.

The available metrics are drawn directly from the CockroachDB Prometheus endpoint and are intended for use as building blocks for your own charts.

Enable percentiles for selected metrics

A subset of CockroachDB metrics require that you explicitly enable percentiles for them in the Datadog interface. Graphs that display data for these metrics will fail to render properly otherwise.

To enable percentiles for these metrics, perform the following steps:

1. In your Datadog interface, select Metrics then Summary from the sidebar.
2. Check the Distributions checkbox in the Metric Type section to limit returned metrics to the subset of CockroachDB metrics that require percentiles support.
3. For each metric shown:
   1. Select the metric and expand its Advanced section.
   2. Click the Edit button.
   3. Click the slider labeled Enable percentiles and threshold queries.
   4. Click the Save button.

You only need to perform this once per metric. Datadog graphs reliant on these metrics will begin rendering immediately once configured in this manner.

Only data received for these metrics once percentiles are enabled can be displayed; any data collected before enabling percentiles for these specific metrics cannot be rendered.

Available metrics

To preview the metrics being collected, you can:

• Click on your cluster's entry in the Infrastructure List to display time-series graphs for each available metric.
• Use the Metrics Explorer to search for and view crdb_cloud metrics.

See Metrics for the full list of metrics available in CockroachDB.

Monitor health of metrics export

To monitor the health of metrics export in a CockroachDB Advanced cluster, we recommend that you create a new Monitor.

Select Threshold Alert as the detection method, which configures an alert that is sent when a supported metric reaches a given threshold. For descriptions of some useful CockroachDB alerts, see Monitoring and Alerting.

• To Define the metric:

  • Select the otel.datadog_exporter.metrics.running metric.
  • Export the metric from your CockroachDB Advanced cluster (the cluster name in the Infrastructure List).

• To Set alert conditions:

  • Trigger when the metric is below the threshold on average during the last 15 minutes.
  • Set Alert threshold to 1.
  • Notify if data is missing for more than 15 minutes.

This monitor will notify your organization if Datadog is no longer receiving data from your CockroachDB Advanced cluster.

Update integration

To update the metadata associated with the integration (for example, to rotate API keys):

1. In the Datadog panel, click the ellipsis and select Update.

2. Update the API key and Datadog Site fields and click Create. The integration will be redeployed.

Deactivate integration

To deactivate the integration:

1. In the Datadog panel, click the ellipsis and select Deactivate integration.

2. When disabled, the Integration status in the panel will show as Inactive.

After deactivating an integration, the metrics data will remain in Datadog for a default retention period.

Monitor CockroachDB Cloud with Amazon CloudWatch integration

The CockroachDB Cloud integration for [Amazon CloudWatch]((https://aws.amazon.com/cloudwatch/) enables data collection and alerting on CockroachDB metrics available at the Prometheus endpoint. It is only available with CockroachDB Standard and Advanced clusters hosted on AWS.

Enable

To enable Amazon CloudWatch monitoring for a CockroachDB Standard or Advanced cluster hosted on AWS, you can either:

• Use the Cloud API, following the instructions on Export Metrics From a CockroachDB Standard Cluster or Export Metrics From a CockroachDB Advanced Cluster.

OR

• Use the Cloud Console, following the steps below.

1. On the cluster's Tools page, click Setup in the CloudWatch panel.

2. Fill in the Role ARN, Target Region, and Log Group Name fields with their corresponding values.

   • The Role ARN is in the format: arn:aws:iam::{role_arn}:role/{role_name}. To determine {role_arn} and {role_name}, follow the steps in the Enable metrics export section on Export Metrics From a CockroachDB Standard Cluster or Export Metrics From a CockroachDB Advanced Cluster.
   • The Target Region is your AWS region, like us-east-1. Specifying an AWS region that you do not have a cluster in, or a region that only partially covers your cluster, will result in missing metrics.
   • The Log Group Name is the target Amazon CloudWatch log group you used when creating the role in the Role ARN.

3. Click Create. Depending on the size of your cluster and the current load on the system, the integration might take some time to become enabled.

4. Once metrics export has been enabled, you can access metrics from your CockroachDB Standard cluster directly in Amazon CloudWatch.

Verify status

Once enabled, the Integration status in the CloudWatch panel on the Tools page will show as Active.

If an issue is encountered during the integration, one of the following statuses may appear instead:

• Active indicates that the integration has been successfully deployed.
• Inactive indicates that the integration has not been successfully deployed. Setup has either not been attempted or has encountered an error.
• Unknown indicates that an unknown error has occurred. If this status is displayed, contact our support team.

In the event of transient CockroachDB unavailability, metrics export from CockroachDB can be interrupted. In this case, the integration status will continue to be Active but you might experience incomplete metrics exports in CloudWatch. To resolve the issue, try deactivating and reactivating the integration from the CloudWatch panel. If this does not resolve the issue, contact our support team.

Update

To update the metadata associated with the integration:

1. In the CloudWatch panel, click the ellipsis and select Update.

2. Update the Role ARN, Target Region, and Log Group Name fields and click Create. The integration will be redeployed.

Deactivate

To deactivate the integration:

1. In the CloudWatch panel, click the ellipsis and select Deactivate integration.

2. When disabled, the Integration status in the panel will show as Inactive.

Access the DB Console

For CockroachDB Advanced clusters, to access the DB Console:

1. On the cluster's Tools page, click Open DB Console in the DB Console panel.

   You can also access the DB Console by navigating to https://admin-{cluster-name}crdb.io:8080/#/metrics/overview/cluster. Replace the {cluster-name} placeholder with the name of your cluster.

2. Log in with your SQL username and password.

Explore the DB Console

• For an overview of all the areas of the DB Console, see DB Console Overview.
• Be sure to check out the Node Map, which visualizes the geographic configuration of your cluster on a world map and provides real-time cluster metrics, with the ability to drill down to individual nodes. This Enterprise feature has been pre-configured and enabled for you.