📣New in Public Preview: TiDB Cloud BYOC, TiDB Cloud Filesystem, PostgreSQL-compatible TiDB Cloud Starter

Integrate TiDB Cloud with New Relic (PREVIEW)

TiDB Cloud supports integration with New Relic. You can configure TiDB Cloud to send metrics for your TiDB Cloud Essential instances to New Relic. After that, you can view these metrics in your New Relic dashboards directly.

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 at https://newrelic.com/signup.
To set up third-party metrics integration for TiDB Cloud, you must have the Organization Owner, Project Owner, or Instance Manager access in TiDB Cloud. To view the integration page, you need at least the Project Viewer or Instance Viewer role to access the target TiDB Cloud Essential instance under your organization in TiDB Cloud.

Limitations

New Relic integration is not available for TiDB Cloud Starter instances.
New Relic integration is not available when the status of your TiDB Cloud Essential instance is CREATING, RESTORING, PAUSED, or RESUMING.
When an instance with the New Relic integration is deleted, its associated integration service is also removed.

Steps

Step 1. Import the pre-built New Relic dashboard

Currently, the TiDB Cloud dashboard for TiDB Cloud Essential is not yet available in the New Relic marketplace. Before it is published, you need to manually download and import the dashboard JSON file into New Relic.

Download the New Relic dashboard JSON file for your instance type:
- For TiDB Cloud Essential instances created on or after July 1, 2026, download this JSON file: https://github.com/pingcap/docs/blob/master/tidb-cloud/monitor-new-relic-integration-tidb-cloud-dynamic-tracker-essential-v2.json. Note that the v2 suffix indicates only the version of the dashboard JSON file.
- For TiDB Cloud Essential instances created before July 1, 2026, download this JSON file: https://github.com/pingcap/docs/blob/master/tidb-cloud/monitor-new-relic-integration-tidb-cloud-dynamic-tracker-essential.json.
In the JSON file, add your New Relic account ID to all "accountIds": [] fields.
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 the contents of the prepared JSON file into the text area, select the permission settings, and then click Save.

Step 2. Integrate with your New Relic API key

In the TiDB Cloud console, navigate to the My TiDB page, and then click the name of your target TiDB Cloud Essential instance to go to its overview page.
In the left navigation pane, click Integrations.
On the Integrations page, locate the New Relic (PREVIEW) integration and click Connect.
Enter your New Relic API key, select the region where your New Relic account is hosted, and then 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.

View the pre-built dashboard

To view the pre-built dashboard after the integration, go to Dashboards > Dashboard List in New Relic, and then select the dashboard imported in Step 1. On the dashboard page, you can filter by your target instance name or instance ID, and then view the metrics.

You can also access the Dashboard List page in New Relic from the TiDB Cloud console: go to the Integrations page of your target instance, click New Relic (PREVIEW), and then click Dashboard.

Metrics available to New Relic

New Relic tracks the following metrics for your TiDB Cloud Essential instance.

Note

The tidb_cloud.cdc_changefeed_* metrics are available only for TiDB Cloud Essential instances created on or after July 1, 2026.

Metric name	Metric type	Labels	Description
`tidb_cloud.db_total_connection`	gauge	`instance_id: <instance id>` `instance_name: <instance name>`	The number of current connections in your TiDB server
`tidb_cloud.db_active_connections`	gauge	`instance_id: <instance id>` `instance_name: <instance name>`	The number of active connections
`tidb_cloud.db_disconnections`	gauge	`result: Error\\|...` `instance_id: <instance id>` `instance_name: <instance name>`	The number of clients disconnected by connection result
`tidb_cloud.db_database_time`	gauge	`sql_type: Select\\|Insert\\|...` `instance_id: <instance id>` `instance_name: <instance name>`	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\\|...` `instance_id: <instance id>` `instance_name: <instance name>`	The number of SQL statements executed per second, counted according to statement types
`tidb_cloud.db_failed_queries`	gauge	`type: planner:xxx\\|executor:2345\\|...` `instance_id: <instance id>` `instance_name: <instance name>`	The statistics of error types (such as syntax errors and primary key conflicts) that occur per second when executing SQL statements
`tidb_cloud.db_command_per_second`	gauge	`type: Query\\|Ping\\|...` `instance_id: <instance id>` `instance_name: <instance name>`	The number of commands processed by TiDB per second
`tidb_cloud.db_queries_using_plan_cache_ops`	gauge	`instance_id: <instance id>` `instance_name: <instance name>`	The number of queries that hit the execution plan cache per second
`tidb_cloud.db_average_query_duration`	gauge	`sql_type: Select\\|Insert\\|...` `instance_id: <instance id>` `instance_name: <instance name>`	The duration between the time a network request is sent to TiDB and the time a response is returned to the client
`tidb_cloud.db_transaction_per_second`	gauge	`type: Commit\\|Rollback\\|...` `txn_mode: optimistic\\|pessimistic` `instance_id: <instance id>` `instance_name: <instance name>`	The number of transactions executed per second
`tidb_cloud.db_row_storage_used_bytes`	gauge	`instance_id: <instance id>` `instance_name: <instance name>`	The row-based storage size of the TiDB Cloud Essential instance in bytes
`tidb_cloud.db_columnar_storage_used_bytes`	gauge	`instance_id: <instance id>` `instance_name: <instance name>`	The columnar storage size of the TiDB Cloud Essential instance in bytes. Returns 0 if TiFlash is not enabled.
`tidb_cloud.resource_manager_resource_request_unit_total`	gauge	`instance_id: <instance id>` `instance_name: <instance name>`	The total Request Units/s (RU/s) consumed
`tidb_cloud.cdc_changefeed_latency`	gauge	`changefeed_id: <changefeed-id>` `instance_id: <instance id>` `instance_name: <instance name>`	The data replication latency between the upstream and the downstream of a changefeed
`tidb_cloud.cdc_changefeed_status`	gauge	`changefeed_id: <changefeed-id>` `instance_id: <instance id>` `instance_name: <instance name>`	Changefeed status: `-1`: Unknown `0`: Normal `1`: Warning `2`: Failed `3`: Stopped `4`: Finished `6`: Warning `7`: Other