📣

TiDB Cloud Serverless is now
TiDB Cloud Starter
! Same experience, new name.
Try it out →

Integrate TiDB Cloud with New Relic (Preview)

TiDB Cloud supports New Relic integration (Preview). 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 New Relic integration (Beta) since April 11, 2023. Starting from July 31, 2025, TiDB Cloud introduces an enhanced preview version of the integration.

  • New Relic integration (Preview): if no Datadog or New Relic integration remains undeleted within your organization by July 31, 2025, TiDB Cloud provides the preview version of New Relic integration so you can experience the latest enhancements.
  • New Relic integration (Beta): if at least one Datadog or New Relic integration remains undeleted within your organization by July 31, 2025, TiDB Cloud retains both existing and new integrations in the beta version to avoid affecting current dashboards. We will also proactively reach out to you to discuss a suitable migration plan and timeline.

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 clusters under your project in TiDB Cloud.

Limitation

  • You cannot use the New Relic integration in TiDB Cloud Starter or TiDB Cloud Essential 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.

    1. In the TiDB Cloud console, navigate to the Clusters page of your project, and then click the name of your target cluster to go to its overview page.

    2. In the left navigation pane, click Settings > Integrations.

    3. On the Integrations page, click Integration to New Relic (Preview).

    4. Enter your API key of New Relic and choose the site of New Relic.

    5. 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.
    6. Click Confirm to complete the integration.

    1. In the TiDB Cloud console, switch to your target project using the combo box in the upper-left corner.

    2. In the left navigation pane, click Project Settings > Integrations.

    3. On the Integrations page, click Integration to New Relic (BETA).

    4. Enter your API key of New Relic and choose the site of New Relic.

    5. 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.
    6. 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:

      1. 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 ],
      2. Log in to New Relic, click Dashboards in the left navigation bar, and then click Import dashboard in the upper-right corner.

      3. In the displayed dialog, paste all the content in the prepared JSON file to the text area, and then click Import dashboard.

      1. Log in to New Relic.
      2. 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.
      3. Choose your account ID and create the dashboard in New Relic.

      View the pre-built dashboard

      1. In the TiDB Cloud console, navigate to the Integrations page.

      2. Click the Dashboard link in the New Relic section to view the pre-built dashboard of your TiDB clusters.

      3. Depending on your New Relic integration version, do one of the following:

        • For New Relic integration (Preview), click TiDB Cloud Dynamic Tracker to view the new dashboard.
        • For 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 nameMetric typeLabelsDescription
      tidb_cloud.db_database_timegaugesql_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_secondgaugetype: Select|Insert|...

      cluster_name: <cluster name>

      instance: tidb-0|tidb-1…

      component: tidb
      The number of SQL statements executed per second on all TiDB instances, which is counted according to SELECT, INSERT, UPDATE, and other types of statements.
      tidb_cloud.db_average_query_durationgaugesql_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_queriesgaugetype: 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 instance.
      tidb_cloud.db_total_connectiongaugecluster_name: <cluster name>

      instance: tidb-0|tidb-1…

      component: tidb
      The number of current connections in your TiDB server.
      tidb_cloud.db_active_connectionsgaugecluster_name: <cluster name>

      instance: tidb-0|tidb-1…

      component: tidb
      The number of active connections.
      tidb_cloud.db_disconnectionsgaugeresult: ok|error|undetermined

      cluster_name: <cluster name>

      instance: tidb-0|tidb-1…

      component: tidb
      The number of disconnected clients.
      tidb_cloud.db_command_per_secondgaugetype: 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_opsgaugecluster_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_secondgaugetxn_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_bytesgaugecluster_name: <cluster name>

      instance: tikv-0|tikv-1…|tiflash-0|tiflash-1…

      component: tikv|tiflash
      The disk usage of TiKV/TiFlash nodes, in bytes.
      tidb_cloud.node_storage_capacity_bytesgaugecluster_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_totalcountcluster_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_coresgaugecluster_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_bytesgaugecluster_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_bytesgaugecluster_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 New Relic integration (Preview), the following additional metrics are also available:

      Metric nameMetric typeLabelsDescription
      tidbcloud.node_storage_available_bytesgaugeinstance: tidb-0\|tidb-1\|...
      component: tikv\|tiflash
      cluster_name: <cluster name>
      The available disk space in bytes for TiKV or TiFlash nodes.
      tidbcloud.disk_read_latencygaugeinstance: tidb-0\|tidb-1\|...
      component: tikv\|tiflash
      cluster_name: <cluster name>
      device: nvme.*\|dm.*
      The read latency (in seconds) per storage device.
      tidbcloud.disk_write_latencygaugeinstance: tidb-0\|tidb-1\|...
      component: tikv\|tiflash
      cluster_name: <cluster name>
      device: nvme.*\|dm.*
      The write latency (in seconds) per storage device.
      tidbcloud.kv_request_durationhistograminstance: tidb-0\|tidb-1\|...
      component: tikv
      cluster_name: <cluster name>
      type: BatchGet\|Commit\|Prewrite\|...
      The duration (in seconds) of TiKV requests by type.
      tidbcloud.component_uptimegaugeinstance: tidb-0\|tidb-1\|...
      component: tidb\|tikv\|tiflash
      cluster_name: <cluster name>
      The uptime (in seconds) of TiDB components.
      tidbcloud.ticdc_owner_checkpoint_ts_laggaugechangefeed_id: <changefeed-id>
      cluster_name: <cluster name>
      The checkpoint timestamp lag (in seconds) for changefeed owner.
      tidbcloud.ticdc_owner_resolved_ts_laggaugechangefeed_id: <changefeed-id>
      cluster_name: <cluster name>
      The resolved timestamp lag (in seconds) for the changefeed owner.
      tidbcloud.changefeed_statusgaugechangefeed_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
      tidbcloud.resource_manager_resource_unit_read_request_unitgaugecluster_name: <cluster name>
      resource_group: <group-name>
      The read request units (RUs) consumed by Resource Manager.
      tidbcloud.resource_manager_resource_unit_write_request_unitgaugecluster_name: <cluster name>
      resource_group: <group-name>
      The write request units (RUs) consumed by Resource Manager.
      tidb_cloud.dm_task_stategaugeinstance: 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_bucketgaugeinstance: instance
      cluster_name: <cluster name>
      Replicate lag (bucket) of Data Migration.
      tidb_cloud.dm_syncer_replication_lag_gaugegaugeinstance: instance
      task: task
      cluster_name: <cluster name>
      Replicate lag (gauge) of Data Migration.
      tidb_cloud.dm_relay_read_error_countgaugeinstance: instance
      cluster_name: <cluster name>
      Fail to read binlog from master.

      Was this page helpful?