CockroachDB Cloud

Pull metrics from CockroachDB Cloud into Oodle through the Prometheus metric export API.

Oodle scrapes each cluster region on a schedule using a service-account API key you provide. Nothing runs in your infrastructure, and no collector is involved.

CockroachDB Standard only

The Prometheus metric export is available on CockroachDB Standard clusters. Basic and Advanced do not offer it. For a cluster you run yourself, see the CockroachDB integration instead, which scrapes /_status/vars with an OpenTelemetry Collector.

Prerequisites

• A CockroachDB Standard cluster
• Permission to create a service account in your CockroachDB Cloud organization
• An Oodle account (navigate to ap1, us1 to start setup)

Step 1: Create a service account and grant Metrics Viewer

In the CockroachDB Cloud console, open Governance > Service accounts and create a service account. Then edit its roles and add Metrics Viewer, scoped to the cluster you want to monitor.

Scope the role to the cluster, not the organization

A service account holding only an organization-level role appears to work. It authenticates, and GET /api/v1/clusters returns HTTP 200 with an empty list rather than a permission error, so it reads as "no clusters exist". Only the per-cluster call reveals the problem, with a 403.

If Oodle reports that it cannot read the metric export, this is the usual cause.

Create an API key for the service account and copy it. The key is shown once.

Step 2: Enable the Prometheus metric export

The export is off by default and there is no control for it in the console: the Integrations page offers Datadog and CloudWatch only. Enable it with the Cloud API.

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/metricexport/prometheus \
  --header "Authorization: Bearer {api_key}"

{cluster_id} is the UUID in your cluster's console URL.

Enabling needs a higher role than scraping

The POST requires Cluster Operator or Cluster Admin (EDIT permission). Metrics Viewer is read-only and gets a 403 here, so this call may need a different key from the one you give Oodle. That is expected: Oodle only ever needs read access.

Confirm the export is live. Enabling takes about a minute.

curl --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/metricexport/prometheus \
  --header "Authorization: Bearer {api_key}"

{
  "cluster_id": "05d234fc-9c7b-4467-b609-a5ed83ccda03",
  "status": "ENABLED",
  "targets": {
    "us-west-2": "https://cockroachlabs.cloud/api/v1/clusters/.../metricexport/prometheus/us-west-2/scrape"
  }
}

status must read ENABLED. ENABLING is transient. NOT_DEPLOYED means the POST did not take effect.

The targets map holds one scrape URL per region. Oodle reads that map itself, so a multi-region cluster needs no extra configuration here, and a region you add later is picked up automatically.

Step 3: Configure the integration in Oodle

Open the CockroachDB Cloud tile (ap1, us1) and add an account:

Field	Value
Account Name	A label for this set of credentials, for example production
API Key	The service-account API key from step 1
Cluster IDs	One or more cluster UUIDs, comma separated

On save, Oodle checks the export state for each cluster and starts scraping within a minute. Open the Dashboards tab and choose Provision & View Dashboards to import the CockroachDB Cloud dashboards into your Grafana folder.

Verify

Query the sentinel metric that CockroachDB Cloud always exports:

crdb_cloud_prometheus_scrape_active_cluster

• 1: the cluster is serving a workload and exporting metrics.
• 0: the cluster is idle, or the export is not enabled.

An idle cluster exports nothing, and that is normal

CockroachDB Standard scales to zero. While a cluster is idle it returns a successful, well-formed response containing only the sentinel above, set to 0. Every dashboard is then legitimately empty.

So empty dashboards on a quiet cluster are not a misconfiguration. Run a query against the database and the metrics appear within a minute.

What you get

Metric names arrive exactly as CockroachDB Cloud exports them, already namespaced crdb_cloud_*, and every series carries cluster, organization and region labels.

CockroachDB Standard exports roughly 100 metric families covering the SQL and tenant layers:

Group	Covers
crdb_cloud_sql_*	Statement counts by type, execution and service latency, connections, memory
crdb_cloud_tenant_sql_usage_*	Request Units, estimated CPU, provisioned vCPUs, read/write IO, egress
crdb_cloud_txn_*	Commits, aborts, restarts by cause, durations
crdb_cloud_changefeed_*	Emitted messages and bytes, commit latency, checkpoint lag, failures
crdb_cloud_jobs_*	Row-level TTL progress and durations, changefeed job state
crdb_cloud_schedules_backup_*	Scheduled backup outcomes and last completion
crdb_cloud_distsender_*, crdb_cloud_clock_offset_*	KV routing and clock skew

Note that this is a different metric set from a self-hosted cluster, not a renamed one. Standard is a multi-tenant plan, so store, replication, raft and rocksdb metrics are not exported at all.

Oodle ships four dashboards, imported when you save an account:

• CockroachDB Cloud Overview: SQL throughput, latency percentiles, transaction health, errors
• CockroachDB Cloud Usage and Cost: Request Units, CPU, storage IO, egress
• CockroachDB Cloud Changefeeds: throughput, commit latency, checkpoint lag
• CockroachDB Cloud Jobs: row-level TTL and scheduled backups

Troubleshooting

Oodle says it cannot read the metric export. The service account is missing the cluster-scoped Metrics Viewer role. An organization-level role is not enough.

The status endpoint reads NOT_DEPLOYED. Run the POST from step 2 with a key that has Cluster Operator or Cluster Admin.

Dashboards are empty and the sentinel reads 0. The cluster is idle. Run a query against it.

Dashboards are empty and the sentinel is missing entirely. Oodle is not scraping. Check that the cluster ID is correct and that the account shows as Receiving in the integration tile.

A changefeed or TTL total looks twice as large as expected. CockroachDB exports those families twice, once as a cluster aggregate and once per scope. Oodle's dashboards disambiguate with scope="" / relation=""; a query you write yourself needs the same filter.