Monitor CockroachDB with Kibana

On this page Carat arrow pointing down
Warning:
GA releases for CockroachDB v23.1 are no longer supported. Cockroach Labs will stop providing LTS Assistance Support for v23.1 LTS releases on November 13, 2025. Prior to that date, upgrade to a more recent version to continue receiving support. For more details, refer to the Release Support Policy.

Kibana is a platform that visualizes data on the Elastic Stack. This page shows how to use the CockroachDB module for Metricbeat to collect metrics exposed by your CockroachDB Self-Hosted cluster's Prometheus endpoint in Elasticsearch and how to visualize those metrics with Kibana.

Tip:

To export metrics from a CockroachDB Cloud cluster, refer to Export Metrics From a CockroachDB Dedicated Cluster instead of this page.

In this tutorial, you will enable the CockroachDB module for Metricbeat and visualize the data in Kibana.

Tip:

For more information about using the CockroachDB module for Metricbeat, see the Elastic documentation.

If you run into problems with this integration, please file an issue on the Beats issue tracker.

Before you begin

Either of the following:

Note:

This tutorial assumes that you have started a secure CockroachDB cluster. CockroachDB Cloud does not expose a compatible monitoring endpoint.

Step 1. Enable CockroachDB module

From your Metricbeat installation directory, run:

icon/buttons/copy
./metricbeat modules enable cockroachdb

Configure security certificates

Open modules.d/cockroachdb.yml in your Metricbeat installation directory.

Follow the steps in the Elastic documentation to enable SSL on the CockroachDB module.

For example, if you used cockroach cert to secure your cluster, the YAML should look like:

- module: cockroachdb
  metricsets: ['status']
  period: 10s
  hosts: ['localhost:8080']
  enabled: true
  ssl.verification_mode: full
  ssl.certificate_authorities: "/custom/dir/path/ca.crt"
  ssl.certificate: "/custom/dir/path/client.root.crt"
  ssl.key: "/custom/dir/path/client.root.key"

ssl.certificate_authorities, ssl.certificate, and ssl.key should specify the full file paths to your CA certificate, client certificate, and client key, respectively.

Step 2. Start Metricbeat

Load the Kibana dashboards (this may take a few moments):

icon/buttons/copy
./metricbeat setup

Launch Metricbeat:

icon/buttons/copy
./metricbeat -e

Step 3. View CockroachDB dashboards on Kibana

Open the Kibana web interface and click Dashboard.

Search for the CockroachDB dashboard:

CockroachDB dashboard selection for Metricbeat

Click the dashboard title to open the dashboard, which presents metrics on replicas and query performance:

CockroachDB Overview dashboard for Metricbeat

Step 4. Run a sample workload

To test the dashboard functionality, use cockroach workload to run a sample workload on the cluster.

Initialize the workload for MovR, a fictional vehicle-sharing company:

icon/buttons/copy
cockroach workload init movr 'postgresql://root@localhost:26257?sslcert=certs%2Fclient.root.crt&sslkey=certs%2Fclient.root.key&sslmode=verify-full&sslrootcert=certs%2Fca.crt'

Run the MovR workload for 5 minutes:

icon/buttons/copy
cockroach workload run movr --duration=5m 'postgresql://root@localhost:26257?sslcert=certs%2Fclient.root.crt&sslkey=certs%2Fclient.root.key&sslmode=verify-full&sslrootcert=certs%2Fca.crt'

Click Refresh. The query metrics will appear on the dashboard:

CockroachDB Overview dashboard for Metricbeat with SQL metrics

Step 5. Disable DB Console's local storage of metrics (optional)

If you rely on external tools such as Kibana for storing and visualizing your cluster's time-series metrics, Cockroach Labs recommends that you disable the DB Console's storage of time-series metrics.

When storage of time-series metrics is disabled, the cluster continues to expose its metrics via the Prometheus endpoint. The DB Console stops storing new time-series cluster metrics and eventually deletes historical data. The Metrics dashboards in the DB Console are still available, but their visualizations are blank. This is because the dashboards rely on data that is no longer available. You can create queries, visualizations, and alerts in Kibana based on the data it is collecting from your cluster's Prometheus endpoint.

See also


Yes No
On this page

Yes No