Integrate TiDB Cloud with New Relic

TiDB Cloud supports New Relic integration. You can configure TiDB Cloud to send metrics of your TiDB clusters to New Relic. After that, you can directly view these metrics in your New Relic dashboards.

New Relic integration version

TiDB Cloud has supported the project-level New Relic integration (Beta) since April 11, 2023. Starting from July 31, 2025, TiDB Cloud introduces the cluster-level New Relic integration (Preview). Starting from September 30, 2025, the cluster-level New Relic integration becomes generally available (GA).

Cluster-level New Relic integration: if no legacy project-level Datadog or New Relic integration remains undeleted within your organization by July 31, 2025, TiDB Cloud provides the cluster-level New Relic integration for your organization to experience the latest enhancements.
Legacy project-level New Relic integration (Beta): if at least one legacy project-level Datadog or New Relic integration remains undeleted within your organization by July 31, 2025, TiDB Cloud retains both existing and new integrations at the project level for your organization to avoid affecting current dashboards. Note that the legacy project-level New Relic integrations will be deprecated on October 31, 2025. If your organization is still using these legacy integrations, follow Migrate Datadog and New Relic Integrations to migrate to the new cluster-level integrations and minimize disruptions to your metrics-related services.

Prerequisites

To integrate TiDB Cloud with New Relic, you must have a New Relic account and create a New Relic API key of the Ingest - License type.
If you do not have a New Relic account, sign up here.
To set up third-party metrics integration for TiDB Cloud, you must have the Organization Owner or Project Owner access in TiDB Cloud. To view the integration page or access configured dashboards via the provided links, you need at least the Project Viewer role to access the target TiDB Cloud Dedicated clusters under your project in TiDB Cloud.

Limitation

New Relic integrations are now only available for TiDB Cloud Dedicated clusters.
New Relic integrations are not available when the cluster status is CREATING, RESTORING, PAUSED, or RESUMING.
When a cluster with New Relic integration is deleted, its associated integration services are also removed.

Steps

Step 1. Integrate with your New Relic API Key

Depending on your New Relic integration version, the steps to access the integration page are different.

In the TiDB Cloud console, navigate to the My TiDB page, and then click the name of your target TiDB Cloud Dedicated cluster to go to its overview page.
In the left navigation pane, click Settings > Integrations.
On the Integrations page, click Integration to New Relic.
Enter your API key of New Relic and choose the site of New Relic.
Click Test Integration.
- If the test succeeds, the Confirm button is displayed.
- If the test fails, an error message is displayed. Follow the message for troubleshooting and retry the integration.
Click Confirm to complete the integration.

In the TiDB Cloud console, navigate to the My TiDB page of your organization, and then click the Project view tab.
In the project view, locate your target project, and then click for the project.
In the left navigation pane, click Integrations under Project Settings.
On the Integrations page, click Integration to New Relic (BETA).
Enter your API key of New Relic and choose the site of New Relic.
Click Test Integration.
- If the test succeeds, the Confirm button is displayed.
- If the test fails, an error message is displayed. Follow the message for troubleshooting and retry the integration.
Click Confirm to complete the integration.

Step 2. Add TiDB Cloud dashboard in New Relic

Depending on your New Relic integration version, the steps are different.

A new TiDB Cloud dashboard will be available in New Relic after the pending PR is merged by New Relic. Before that, you can manually import the dashboard to New Relic by taking the following steps:

Prepare the JSON file for the new dashboard.
1. Download the template JSON file here.
2. In the JSON file, add "permissions": "PUBLIC_READ_WRITE" to line 4 as follows:
```
{
  "name": "TiDB Cloud Dynamic Tracker",
  "description": null,
  "permissions": "PUBLIC_READ_WRITE",
  ...
}
```
3. Add your New Relic account ID to all "accountIds": [] fields in the JSON file.
  For example:
```
"accountIds": [
  1234567
],
```
  Note
  To avoid integration errors, make sure your account ID is added in all "accountIds" fields in the JSON file.
Log in to New Relic, click Dashboards in the left navigation bar, and then click Import dashboard in the upper-right corner.
In the displayed dialog, paste all the content in the prepared JSON file to the text area, and then click Import dashboard.

Log in to New Relic.
Click Add Data, search for TiDB Cloud, and then go to the TiDB Cloud Monitoring page. Alternatively, you can click the link to directly access the page.
Choose your account ID and create the dashboard in New Relic.

View the pre-built dashboard

In the TiDB Cloud console, navigate to the Integrations page.
Click the Dashboard link in the New Relic section to view the pre-built dashboard of your TiDB clusters.
Depending on your New Relic integration version, do one of the following:
- For cluster-level New Relic integration, click TiDB Cloud Dynamic Tracker to view the new dashboard.
- For legacy project-level New Relic integration (Beta), click TiDB Cloud Monitoring to view the legacy dashboard.

Metrics available to New Relic

New Relic tracks the following metrics for your TiDB clusters.

Metric name	Metric type	Labels	Description
tidb_cloud.db_database_time	gauge	sql_type: Select\|Insert\|... cluster_name: `<cluster name>` instance: tidb-0\|tidb-1… component: `tidb`	The total time consumed by all SQL statements running in TiDB per second, including the CPU time of all processes and the non-idle waiting time.
tidb_cloud.db_query_per_second	gauge	type: Select\|Insert\|... cluster_name: `<cluster name>` instance: tidb-0\|tidb-1… component: `tidb`	The number of SQL statements executed per second on all TiDB nodes, which is counted according to `SELECT`, `INSERT`, `UPDATE`, and other types of statements.
tidb_cloud.db_average_query_duration	gauge	sql_type: Select\|Insert\|... cluster_name: `<cluster name>` instance: tidb-0\|tidb-1… component: `tidb`	The duration between the time that the client's network request is sent to TiDB and the time that the request is returned to the client after TiDB has executed it.
tidb_cloud.db_failed_queries	gauge	type: executor:xxxx\|parser:xxxx\|... cluster_name: `<cluster name>` instance: tidb-0\|tidb-1… component: `tidb`	The statistics of error types (such as syntax errors and primary key conflicts) according to the SQL execution errors that occur per second on each TiDB node.
tidb_cloud.db_total_connection	gauge	cluster_name: `<cluster name>` instance: tidb-0\|tidb-1… component: `tidb`	The number of current connections in your TiDB server.
tidb_cloud.db_active_connections	gauge	cluster_name: `<cluster name>` instance: tidb-0\|tidb-1… component: `tidb`	The number of active connections.
tidb_cloud.db_disconnections	gauge	result: ok\|error\|undetermined cluster_name: `<cluster name>` instance: tidb-0\|tidb-1… component: `tidb`	The number of disconnected clients.
tidb_cloud.db_command_per_second	gauge	type: Query\|StmtPrepare\|... cluster_name: `<cluster name>` instance: tidb-0\|tidb-1… component: `tidb`	The number of commands processed by TiDB per second, which is classified according to the success or failure of command execution results.
tidb_cloud.db_queries_using_plan_cache_ops	gauge	cluster_name: `<cluster name>` instance: tidb-0\|tidb-1… component: `tidb`	The statistics of queries using Plan Cache per second. The execution plan cache only supports the prepared statement command.
tidb_cloud.db_transaction_per_second	gauge	txn_mode: pessimistic\|optimistic type: abort\|commit\|... cluster_name: `<cluster name>` instance: tidb-0\|tidb-1… component: `tidb`	The number of transactions executed per second.
tidb_cloud.node_storage_used_bytes	gauge	cluster_name: `<cluster name>` instance: tikv-0\|tikv-1…\|tiflash-0\|tiflash-1… component: tikv\|tiflash	The disk usage, in bytes, for TiKV or TiFlash nodes. This metric primarily represents the logical data size in the storage engine, and excludes WAL files and temporary files. To calculate the actual disk usage rate, use `(capacity - available) / capacity` instead. When the storage usage of TiKV exceeds 80%, latency spikes might occur, and higher usage might cause requests to fail. When the storage usage of all TiFlash nodes reaches 80%, any DDL statement that adds a TiFlash replica hangs indefinitely.
tidb_cloud.node_storage_capacity_bytes	gauge	cluster_name: `<cluster name>` instance: tikv-0\|tikv-1…\|tiflash-0\|tiflash-1… component: tikv\|tiflash	The disk capacity of TiKV/TiFlash nodes, in bytes.
tidb_cloud.node_cpu_seconds_total (Beta only)	count	cluster_name: `<cluster name>` instance: tidb-0\|tidb-1…\|tikv-0…\|tiflash-0… component: tidb\|tikv\|tiflash	The CPU usage of TiDB/TiKV/TiFlash nodes.
tidb_cloud.node_cpu_capacity_cores	gauge	cluster_name: `<cluster name>` instance: tidb-0\|tidb-1…\|tikv-0…\|tiflash-0… component: tidb\|tikv\|tiflash	The limit on CPU cores of TiDB/TiKV/TiFlash nodes.
tidb_cloud.node_memory_used_bytes	gauge	cluster_name: `<cluster name>` instance: tidb-0\|tidb-1…\|tikv-0…\|tiflash-0… component: tidb\|tikv\|tiflash	The used memory of TiDB/TiKV/TiFlash nodes, in bytes.
tidb_cloud.node_memory_capacity_bytes	gauge	cluster_name: `<cluster name>` instance: tidb-0\|tidb-1…\|tikv-0…\|tiflash-0… component: tidb\|tikv\|tiflash	The memory capacity of TiDB/TiKV/TiFlash nodes, in bytes.

For cluster-level New Relic integrations, the following additional metrics are also available:

Metric name	Metric type	Labels	Description
tidb_cloud.node_storage_available_bytes	gauge	instance: `tidb-0\\|tidb-1\\|...` component: `tikv\\|tiflash` cluster_name: `<cluster name>`	The available disk space in bytes for TiKV or TiFlash nodes.
tidb_cloud.node_disk_read_latency	gauge	instance: `tidb-0\\|tidb-1\\|...` component: `tikv\\|tiflash` cluster_name: `<cluster name>` `device`: `nvme.\\|dm.`	The read latency (in seconds) per storage device.
tidb_cloud.node_disk_write_latency	gauge	instance: `tidb-0\\|tidb-1\\|...` component: `tikv\\|tiflash` cluster_name: `<cluster name>` `device`: `nvme.\\|dm.`	The write latency (in seconds) per storage device.
tidb_cloud.db_kv_request_duration	gauge	instance: `tidb-0\\|tidb-1\\|...` component: `tikv` cluster_name: `<cluster name>` `type`: `BatchGet\\|Commit\\|Prewrite\\|...`	The duration (in seconds) of TiKV requests by type.
tidb_cloud.db_component_uptime	gauge	instance: `tidb-0\\|tidb-1\\|...` component: `tidb\\|tikv\\|tiflash` cluster_name: `<cluster name>`	The uptime (in seconds) of TiDB components.
tidb_cloud.cdc_changefeed_latency (AKA cdc_changefeed_checkpoint_ts_lag)	gauge	changefeed_id: `<changefeed-id>` cluster_name: `<cluster name>`	The checkpoint timestamp lag (in seconds) for changefeed owner.
tidb_cloud.cdc_changefeed_resolved_ts_lag	gauge	changefeed_id: `<changefeed-id>` cluster_name: `<cluster name>`	The resolved timestamp lag (in seconds) for the changefeed owner.
tidb_cloud.cdc_changefeed_status	gauge	changefeed_id: `<changefeed-id>` cluster_name: `<cluster name>`	Changefeed status: `-1`: Unknown `0`: Normal `1`: Warning `2`: Failed `3`: Stopped `4`: Finished `6`: Warning `7`: Other
tidb_cloud.resource_manager_resource_unit_read_request_unit	gauge	cluster_name: `<cluster name>` resource_group: `<group-name>`	The read request units (RUs) consumed by Resource Manager.
tidb_cloud.resource_manager_resource_unit_write_request_unit	gauge	cluster_name: `<cluster name>` resource_group: `<group-name>`	The write request units (RUs) consumed by Resource Manager.
tidb_cloud.dm_task_state	gauge	instance: `instance` task: `task` cluster_name: `<cluster name>`	Task State of Data Migration: `0`: Invalid `1`: New `2`: Running `3`: Paused `4`: Stopped `5`: Finished `15`: Error
tidb_cloud.dm_syncer_replication_lag_bucket	gauge	instance: `instance` cluster_name: `<cluster name>`	Replicate lag (bucket) of Data Migration.
tidb_cloud.dm_syncer_replication_lag_gauge	gauge	instance: `instance` task: `task` cluster_name: `<cluster name>`	Replicate lag (gauge) of Data Migration.
tidb_cloud.dm_relay_read_error_count	gauge	instance: `instance` cluster_name: `<cluster name>`	Fail to read binlog from master.
tidb_cloud.node_memory_available_bytes	gauge	cluster_name: `<cluster name>` instance: tidb-0\|tidb-1…\|tikv-0…\|tiflash-0… component: tidb\|tikv\|tiflash	The available memory of TiDB/TiKV/TiFlash nodes, in bytes.
tidb_cloud.cdc_changefeed_replica_rows	gauge	changefeed_id: `<changefeed-id>` cluster_name: `<cluster name>`	The number of events that TiCDC nodes write to the downstream per second.
tidb_cloud.node_cpu_seconds_total_rate	gauge	cluster_name: `<cluster name>` instance: tidb-0\|tidb-1…\|tikv-0…\|tiflash-0… component: tidb\|tikv\|tiflash	The CPU usage of TiDB/TiKV/TiFlash nodes.