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

# Monitor CockroachDB Self-Hosted Clusters with Datadog

[Datadog](https://www.datadoghq.com/) is a monitoring and security platform for cloud applications. The integration of your CockroachDB self-hosted cluster with Datadog enables data collection and alerting on selected [CockroachDB metrics](https://docs.datadoghq.com/integrations/cockroachdb/?tab=host#data-collected) using the Datadog platform.

> [!TIP]
>
> This tutorial explores the CockroachDB self-hosted integration with Datadog. For the CockroachDB Cloud integration with Datadog, refer to [Monitor CockroachDB Dedicated with Datadog](/docs/cockroachcloud/tools-page.md#monitor-cockroachdb-cloud-with-datadog) instead of this page.

The integration of your CockroachDB self-hosted cluster with Datadog is powered by the [Datadog Agent](https://app.datadoghq.com/account/settings#agent), and supported by Datadog directly:

* For more information about the integration, see the [Datadog blog post](https://www.datadoghq.com/blog/monitor-cockroachdb-performance-metrics-with-datadog/).
* For more information about using Datadog, see the [Datadog documentation](https://docs.datadoghq.com/).
* If you run into problems with this integration, please file an issue on the [Datadog Agent issue tracker](https://github.com/DataDog/datadog-agent).

In this tutorial, you will enable the CockroachDB integration in Datadog, configure logging and alerting, and visualize data.

## Before you begin

Before you can follow the steps presented in this tutorial, you must have:

* Downloaded and installed the [Datadog Agent](https://app.datadoghq.com/account/settings#agent).
* Started a [secure CockroachDB self-hosted cluster](/docs/stable/secure-a-cluster.md).

## Step 1. Enable CockroachDB integration

To enable the CockroachDB check for your installed Datadog Agent, navigate to the [Integrations page](https://app.datadoghq.com/account/settings#integrations) and find CockroachDB in the list of available integrations. Hover over the icon and click **+ Install**.

![CockroachDB integration for Datadog installation](https://mintcdn.com/cockroachlabs/Vnu3Mn2DzHS7Vfry/images/common/datadog-crdb-integration.png?fit=max\&auto=format\&n=Vnu3Mn2DzHS7Vfry\&q=85\&s=b5649ca85a1d240c9de78071e4e5d81b)

Note that you must restart the Datadog Agent for the change to take effect. CockroachDB will then be listed as an installed integration.

## Step 2. Configure Datadog Agent for CockroachDB

Follow the steps in the [Datadog documentation](https://docs.datadoghq.com/integrations/cockroachdb/?tab=host#configuration) to access and edit your `cockroachdb.d/conf.yaml` file in your Datadog `conf.d/` directory. For all available options, see the sample [`cockroachdb.d/conf.yaml`](https://github.com/DataDog/integrations-core/blob/master/cockroachdb/datadog_checks/cockroachdb/data/conf.yaml.example).

After making the following changes, restart the Datadog Agent to apply them.

### Enable metrics collection

Uncomment the following line in `cockroachdb.d/conf.yaml`:

```yaml theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
- prometheus_url: http://localhost:8080/_status/vars
```

This enables metrics collection via our [Prometheus endpoint](/docs/stable/prometheus-endpoint.md).

### Configure security certificates

Uncomment the lines that begin with `tls_private_key` and `tls_ca_cert`. These should specify the full file paths to your CA key and certificate, respectively.

For example, if you used [`cockroach cert`](/docs/stable/cockroach-cert) to [secure your cluster](/docs/stable/secure-a-cluster.md#step-1-generate-certificates), the paths would look something like:

```yaml theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
tls_private_key: /custom/dir/path/client.root.key
```

```yaml theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
tls_ca_cert: /custom/dir/path/ca.crt
```

### Enable log collection

Optionally enable Datadog to collect [CockroachDB logs](/docs/stable/logging-overview.md) by adding the following block to `cockroachdb.d/conf.yaml`:

```yaml theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
logs:
 - type: file
   path: /cockroach-data/logs/cockroach.log
   source: cockroachdb
   service: cockroachdb
   log_processing_rules:
   - type: multi_line
     name: new_log_start_with_status_and_date
     pattern: '[A-Z]\d{6}\s\d+\:\d+\:\d+\.\d+'
```

The `path` value specifies the [default](/docs/stable/configure-logs.md#default-logging-configuration) CockroachDB log file and location.

> [!NOTE]
>
> You can configure both the CockroachDB [logging directory](/docs/stable/configure-logs.md#set-file-defaults) and [log files](/docs/stable/configure-logs.md#output-to-files).

Log collection is disabled by default in the Datadog Agent. Follow the steps in the [Datadog documentation](https://docs.datadoghq.com/agent/logs/?tab=tailfiles#activate-log-collection) to activate log collection.

## Step 3. Verify Datadog connection to CockroachDB

To apply your configuration changes, ensure that you have restarted the Datadog Agent.

Run the Datadog Agent [`status` subcommand](https://docs.datadoghq.com/agent/guide/agent-commands/?tab=agentv6v7#agent-information) for your platform to verify that the CockroachDB integration is properly connected.

Your output should contain a block like this:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
cockroachdb (1.6.0)
-------------------
  Instance ID: cockroachdb:42170ecfbfb171c5 [OK]
  Configuration Source: file:/opt/datadog-agent/etc/conf.d/cockroachdb.d/conf.yaml
  Total Runs: 4
  Metric Samples: Last Run: 548, Total: 2,154
  Events: Last Run: 0, Total: 0
  Service Checks: Last Run: 1, Total: 4
  Average Execution Time : 143ms
  Last Execution Date : 2021-07-14 12:34:56 EDT / 2021-07-14 16:34:56 UTC (1626280496000)
  Last Successful Execution Date : 2021-07-14 12:34:56 EDT / 2021-07-14 16:34:56 UTC (1626280496000)
  metadata:
    version.major: 21
    version.minor: 2
    version.patch: 0
    version.raw: v25.3.0-alpha.00000000-1724-gc5c74249f7
    version.release: alpha.0
    version.scheme: semver
```

## Step 4. View CockroachDB dashboards on Datadog

Open your Datadog [Dashboard List](https://app.datadoghq.com/dashboard/lists) and click on `CockroachDB Overview`:

![CockroachDB Overview dashboard in Datadog Dashboard List](https://mintcdn.com/cockroachlabs/Vnu3Mn2DzHS7Vfry/images/common/datadog-crdb-dashboard-list.png?fit=max\&auto=format\&n=Vnu3Mn2DzHS7Vfry\&q=85\&s=073f02f8e9814f8ac277668e8f2f1fcd)

This sample dashboard presents metrics on cluster availability, query performance, and resource usage:

![CockroachDB Overview dashboard for Datadog](https://mintcdn.com/cockroachlabs/Vnu3Mn2DzHS7Vfry/images/common/datadog-crdb-overview-dashboard.png?fit=max\&auto=format\&n=Vnu3Mn2DzHS7Vfry\&q=85\&s=24bb7099d544f9c4142712d85e19b93d)

> [!NOTE]
>
> If you wish to customize your CockroachDB dashboard, it's recommended that you clone the default `CockroachDB Overview` dashboard before adding and removing widgets. If you leave the default dashboard intact, Datadog will update it when new versions of the integration's dashboard are released.

## Step 5. Run a sample workload

To test the dashboard functionality, use [`cockroach workload`](/docs/stable/cockroach-workload) to run a sample workload on the cluster.

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

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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'
```

The query metrics will appear on the dashboard:

![CockroachDB Overview dashboard for Datadog with SQL metrics](https://mintcdn.com/cockroachlabs/Vnu3Mn2DzHS7Vfry/images/common/datadog-crdb-workload-dashboard.png?fit=max\&auto=format\&n=Vnu3Mn2DzHS7Vfry\&q=85\&s=c1069c22555e29c91b86fb93ff11077e)

## Step 6. Add monitoring and alerting

Follow the steps in the [Datadog documentation](https://docs.datadoghq.com/monitors/monitor_types/) to create a new Monitor.

Select **Threshold Alert** as the detection method. You can use this option to configure an alert that is sent when a [supported metric](https://docs.datadoghq.com/integrations/cockroachdb/?tab=host#data-collected) reaches a given threshold. For descriptions of some useful CockroachDB alerts, see [Monitoring and Alerting](/docs/stable/monitoring-and-alerting.md#events-to-alert-on).

The example alert below will trigger when [a node has less than 15% of storage capacity remaining](/docs/stable/monitoring-and-alerting.md#node-is-running-low-on-disk-space):

![CockroachDB Threshold Alert in Datadog](https://mintcdn.com/cockroachlabs/Vnu3Mn2DzHS7Vfry/images/common/datadog-crdb-threshold-alert.png?fit=max\&auto=format\&n=Vnu3Mn2DzHS7Vfry\&q=85\&s=f3f5b794557a3a54a44ba8e071d01d04)

* `cockroachdb.capacity.available` is divided by `cockroachdb.capacity.total` to determine the fraction of available capacity on the node's [store](/docs/stable/architecture/storage-layer.md) (the directory on each node where CockroachDB reads and writes its data).
* The alert threshold is set to `0.15`.

The timeseries graph at the top of the page indicates the configured metric and threshold:

![CockroachDB Threshold Alert in Datadog](https://mintcdn.com/cockroachlabs/Vnu3Mn2DzHS7Vfry/images/common/datadog-crdb-storage-alert.png?fit=max\&auto=format\&n=Vnu3Mn2DzHS7Vfry\&q=85\&s=5bf07a7d1d28a6d304ecbe4ed1273211)

## Known limitations

* The integration of your CockroachDB self-hosted cluster with Datadog only supports displaying cluster-wide averages of reported metrics. Filtering by a specific node is unsupported.

## See also

* [Monitoring and Alerting](/docs/stable/monitoring-and-alerting.md)
* [DB Console Overview](/docs/stable/ui-overview.md)
* [Logging Overview](/docs/stable/logging-overview.md)
* [Metrics](/docs/stable/metrics.md)