> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/integrations/sources/cockroachdb.md). # CockroachDB The CockroachDB source collects metrics and logs from CockroachDB. Metrics are scraped from the CockroachDB Prometheus endpoint (`/_status/vars`) exposed by the DB Console HTTP port. Logs are read from the CockroachDB log files on disk (health, dev, error, SQL schema, telemetry, KV distribution, and Pebble logs). You can enable metrics, logs, or both. ### Supported Telemetry | Platform | Metrics | Logs | Traces | | -------- | ------- | ---- | ------ | | Linux | ✓ | ✓ | | | Windows | ✓ | ✓ | | | macOS | ✓ | ✓ | | ### Prerequisites For metrics: * A reachable CockroachDB node with the DB Console HTTP port accessible from the collector host. The default port is `8080`. * The CockroachDB Prometheus endpoint (`/_status/vars`) is enabled by default. See [Monitor CockroachDB with Prometheus](https://www.cockroachlabs.com/docs/stable/monitor-cockroachdb-with-prometheus). * If the cluster is secure, a CockroachDB user for authentication and TLS material (CA certificate, and a client certificate and key for mutual TLS). Use a least-privilege monitoring account rather than an administrative user. For logs: * CockroachDB writing the log files you want to collect, and read access for the collector to those file paths. * The collector running on the same host as the CockroachDB node so it can read the local log files. ### Configuration
Bindplane docs - CockroachDB - image 1
**Telemetry Type** | Parameter | Type | Required | Default | Description | | --------------------- | ------------------ | -------- | --------------------- | ------------------------------------------------------ | | Choose Telemetry Type | Telemetry Selector | No | `["Logs", "Metrics"]` | Which signals to collect. Valid values: Logs, Metrics. | **Logs** These parameters apply when Metrics includes Logs. | Parameter | Type | Required | Default | Description | | --------------------------- | ------- | -------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | Enable Health Logs | Boolean | No | `true` | Enable to collect health logs. | | Health Log Path | Strings | No | `/var/log/cockroach-data/logs/cockroach-health.log` | The absolute path to the CockroachDB health logs. Relevant when Enable Health Logs is true. | | Enable Dev Logs | Boolean | No | `true` | Enable to collect general developer logs. | | Dev Log Path | Strings | No | `/var/log/cockroach-data/logs/cockroach.log` | The absolute path to the CockroachDB dev logs. Relevant when Enable Dev Logs is true. | | Enable Error Logs | Boolean | No | `true` | Enable to collect stderr logs. | | Error Log Path | Strings | No | `/var/log/cockroach-data/logs/cockroach-stderr.log` | The absolute path to the CockroachDB stderr logs. Relevant when Enable Error Logs is true. | | Enable SQL Schema Logs | Boolean | No | `true` | Enable to collect SQL schema logs. | | SQL Schema Log Path | Strings | No | `/var/log/cockroach-data/logs/cockroach-sql-schema.log` | The absolute path to the CockroachDB SQL schema logs. Relevant when Enable SQL Schema Logs is true. | | Enable Telemetry Logs | Boolean | No | `true` | Enable to collect telemetry logs. | | Telemetry Log Path | Strings | No | `/var/log/cockroach-data/logs/cockroach-telemetry.log` | The absolute path to the CockroachDB telemetry logs. Relevant when Enable Telemetry Logs is true. | | Enable KV Distribution Logs | Boolean | No | `true` | Enable to collect KV distribution logs. | | KV Distribution Log Path | Strings | No | `/var/log/cockroach-data/logs/cockroach-kv-distribution.log` | The absolute path to the CockroachDB KV distribution logs. Relevant when Enable KV Distribution Logs is true. | | Enable Pebble Logs | Boolean | No | `true` | Enable to collect CockroachDB Pebble logs. | | Pebble Log Path | Strings | No | `/var/log/cockroach-data/logs/cockroach-pebble.log` | The absolute path to the CockroachDB Pebble logs. Relevant when Enable Pebble Logs is true. | **Metrics** These parameters apply when Choose Telemetry Type includes Metrics. | Parameter | Type | Required | Default | Description | | --------- | ------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ | | Hostname | String | Yes | `localhost` | The hostname or IP address of the CockroachDB system. | | Port | Integer | No | `8080` | The port to listen on for DB Console HTTP requests. | | Username | String | No | *(empty)* | The username to use when connecting to CockroachDB. | | Password | String | No | *(empty)* | The password to use when connecting to CockroachDB. TLS must be configured in the Advanced section if this field is set. | **Advanced** | Parameter | Type | Required | Default | Description | | --------------------------------- | ---------------------- | -------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | Offset Storage Directory | String | No | `${OIQ_OTEL_COLLECTOR_HOME}/storage` | The directory the offset storage file will be created in. Relevant when collecting Logs. | | Timezone | Timezone | No | `UTC` | The timezone to use when parsing timestamps. Relevant when collecting Logs. | | Start At | Enum: beginning, end | No | `end` | Start reading logs from beginning or end. Relevant when collecting Logs. | | Parse to | Enum: body, attributes | No | `body` | Parse structured log parts to either body or attributes. Relevant when collecting Logs. | | Retain Raw Logs | Boolean | No | `false` | Preserve the original log message in a raw\_log key. Relevant when collecting Logs. | | Parse | Boolean | No | `true` | Parses the log fields into structured data. Relevant when collecting Logs. | | Enable TLS | Boolean | No | `false` | Whether or not to use TLS. Relevant when collecting Metrics. | | TLS Certificate Authority File | String | No | *(empty)* | File path for the CA certification file for CockroachDB (only needed if you have a secure cluster). Relevant when Enable TLS is true. | | TLS Client Certificate File | String | No | *(empty)* | A TLS certificate used for client authentication, if mutual TLS is enabled. Relevant when Enable TLS is true. | | TLS Client Private Key File | String | No | *(empty)* | A TLS private key used for client authentication, if mutual TLS is enabled. Relevant when Enable TLS is true. | | Server Name | String | No | *(empty)* | The name of the server. Relevant when Enable TLS is true. | | Skip TLS Certificate Verification | Boolean | No | `false` | Disable validation of the server certificate. Relevant when Enable TLS is true. | | Collection Interval | Integer | No | `60` | How often (seconds) to scrape for metrics. Relevant when collecting Metrics. | ### Examples #### Collect metrics and logs from a local CockroachDB node This example scrapes metrics from the local DB Console port and reads the default log files. It uses the default insecure (no TLS) configuration. ```yaml - name: telemetry_types value: ["Logs", "Metrics"] - name: hostname value: localhost - name: port value: 8080 ``` #### Collect metrics from a secure cluster over TLS This example connects to a secure cluster with a monitoring user and mutual TLS. ```yaml - name: telemetry_types value: ["Metrics"] - name: hostname value: crdb-node-1.internal - name: port value: 8080 - name: username value: monitoring - name: password value: - name: enable_tls value: true - name: ca_file_path value: /etc/cockroach/certs/ca.crt - name: cert_file_path value: /etc/cockroach/certs/client.monitoring.crt - name: key_file_path value: /etc/cockroach/certs/client.monitoring.key ``` ### Configuration Tips * The Port parameter is the DB Console HTTP port (default `8080`), not the SQL port. Metrics are scraped from the `/_status/vars` endpoint on this port. * Set a Username and Password only on secure clusters. When a Password is set, you must enable TLS in the Advanced section. * Run the collector on the same host as the CockroachDB node so it can read the local log files at the configured paths. ### Troubleshooting #### Connection refused when scraping metrics Symptoms: the metrics receiver cannot reach the endpoint and reports connection refused. Solutions: 1. Confirm the DB Console HTTP port (default `8080`) is correct and reachable from the collector host. 2. Verify any firewall or security group allows traffic from the collector to that port. #### Authentication or TLS handshake failures Symptoms: the receiver connects but fails to authenticate, or the TLS handshake fails. Solutions: 1. On a secure cluster, confirm the Username and Password are valid and TLS is enabled. 2. Verify the CA, client certificate, and client key file paths are correct and readable by the collector. 3. If using a private CA or hostname mismatch, set Server Name or enable Skip TLS Certificate Verification as appropriate. #### No logs are collected Symptoms: no log records appear for an enabled log type. Solutions: 1. Confirm the configured log path exists and CockroachDB is writing to it. 2. Verify the collector process has read permission on the log files. ### Standalone Source ```yaml apiVersion: bindplane.observiq.com/v1 kind: Source metadata: name: cockroachdb spec: type: cockroachdb parameters: - name: telemetry_types value: - Logs - Metrics - name: hostname value: localhost - name: port value: 8080 - name: enable_health_log value: true - name: health_log_path value: - /var/log/cockroach-data/logs/cockroach-health.log - name: enable_dev_log value: true - name: dev_log_path value: - /var/log/cockroach-data/logs/cockroach.log - name: enable_error_log value: true - name: error_log_path value: - /var/log/cockroach-data/logs/cockroach-stderr.log - name: collection_interval value: 60 ``` ### Related Resources * [Monitor CockroachDB with Prometheus](https://www.cockroachlabs.com/docs/stable/monitor-cockroachdb-with-prometheus) * [CockroachDB Prometheus Endpoint](https://www.cockroachlabs.com/docs/stable/prometheus-endpoint) * [CockroachDB Logging overview](https://www.cockroachlabs.com/docs/stable/logging-overview) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bindplane.com/integrations/sources/cockroachdb.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.