📣

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

Integrate TiDB Cloud with Datadog (Preview)

TiDB Cloud supports Datadog integration (Preview). You can configure TiDB Cloud to send metrics about your TiDB clusters to Datadog. After that, you can view these metrics in your Datadog dashboards directly.

Datadog integration version

TiDB Cloud has supported Datadog integration (Beta) since March 04, 2022. Starting from July 31, 2025, TiDB Cloud introduces an enhanced preview version of the integration.

  • Datadog 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 Datadog integration for your organization to experience the latest enhancements.
  • Datadog 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 Datadog, you must have a Datadog account and a Datadog API key. Datadog grants you an API key when you first create a Datadog account.

    If you do not have a Datadog account, sign up at https://app.datadoghq.com/signup.

  • 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 the project in TiDB Cloud.

Limitation

  • You cannot use the Datadog integration in TiDB Cloud Starter or TiDB Cloud Essential clusters.

  • Datadog integrations are not available when the cluster status is CREATING, RESTORING, PAUSED, or RESUMING.

  • When a cluster with Datadog integration is deleted, its associated integration services are also removed.

Steps

Step 1. Integrate with your Datadog API Key

Depending on your Datadog 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 Datadog (PREVIEW).

    4. Enter your Datadog API key and choose your Datadog site.

    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 Datadog (BETA).

    4. Enter your Datadog API key and choose your Datadog site.

    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. Install TiDB Cloud Integration in Datadog

    1. Log in to Datadog.

    2. Go to the TiDB Cloud Integration page in Datadog.

    3. On the Configuration tab, click Install Integration.

    View the pre-built dashboard

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

    2. Click the Dashboard link in the Datadog section.

      • For Datadog integration (Preview), the Dashboard link opens the new dashboard, which includes the latest metrics introduced in the preview version.
      • For Datadog integration (Beta), the Dashboard link opens the legacy dashboard, which does not include the latest metrics introduced in the preview version.

    Metrics available to Datadog

    Datadog 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, counted by the statement type (SELECT, INSERT, or UPDATE).
    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 Datadog integration (Preview), the following additional metrics are also available:

    Metric nameMetric typeLabelsDescription
    tidb_cloud.node_storage_available_bytesgaugeinstance: tidb-0\|tidb-1\|...
    component: tikv\|tiflash
    cluster_name: <cluster name>
    The available disk space in bytes for TiKV/TiFlash nodes.
    tidb_cloud.node_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.
    tidb_cloud.node_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.
    tidb_cloud.db_kv_request_durationgaugeinstance: 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_uptimegaugeinstance: 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)gaugechangefeed_id: <changefeed-id>
    cluster_name: <cluster name>
    The checkpoint timestamp lag (in seconds) for changefeed owner.
    tidb_cloud.cdc_changefeed_resolved_ts_laggaugechangefeed_id: <changefeed-id>
    cluster_name: <cluster name>
    The resolved timestamp lag (in seconds) for the changefeed owner.
    tidb_cloud.cdc_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
    tidb_cloud.resource_manager_resource_unit_read_request_unitgaugecluster_name: <cluster name>
    resource_group: <group-name>
    The read request units (RUs) consumed by Resource Manager.
    tidb_cloud.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.
    tidb_cloud.node_memory_available_bytesgaugecluster_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_rowsgaugechangefeed_id: <changefeed-id>
    cluster_name: <cluster name>
    The number of events that TiCDC nodes write to the downstream per second.

    Was this page helpful?