📣
TiDB Cloud Premium 开放公测中。为企业级工作负载提供无限扩展、即时弹性伸缩和高级安全保障。此页面由 AI 自动翻译，英文原文请见此处。
AI
应用开发
最佳实践
API

集成 TiDB Cloud 与 Prometheus 和 Grafana

TiDB Cloud 提供了一个 Prometheus API 端点。如果你拥有 Prometheus 服务，可以轻松地通过该端点监控 TiDB Cloud 的关键统计/指标（信息）。

本文档介绍了如何配置你的 Prometheus 服务，从 TiDB Cloud 端点读取关键统计/指标（信息），以及如何使用 Grafana 查看这些统计/指标（信息）。

Prometheus 集成版本

自 2022 年 3 月 15 日起，TiDB Cloud 支持项目级 Prometheus 集成（Beta）。自 2025 年 10 月 21 日起，TiDB Cloud 推出集群级 Prometheus 集成（预览版）。自 2025 年 12 月 2 日起，集群级 Prometheus 集成正式可用（GA）。

  • 集群级 Prometheus 集成：如果在 2025 年 10 月 21 日前，你的组织内没有未删除的遗留项目级 Prometheus 集成，TiDB Cloud 将为你的组织提供集群级 Prometheus 集成，以体验最新增强功能。

  • 遗留项目级 Prometheus 集成（Beta）：如果在 2025 年 10 月 21 日前，你的组织内至少有一个未删除的遗留项目级 Prometheus 集成，TiDB Cloud 会在项目级别保留现有和新建的集成，以避免影响当前的仪表盘。

前提条件

  • 若要集成 TiDB Cloud 与 Prometheus，你必须拥有自托管或托管的 Prometheus 服务。

  • 若要为 TiDB Cloud 设置第三方统计/指标（信息）集成，你必须在 TiDB Cloud 中拥有 Organization Owner 或 Project Owner 访问权限。若要查看集成页面，至少需要 Project Viewer 角色以访问项目下的目标 TiDB Cloud Dedicated 集群。

限制

  • Prometheus 和 Grafana 集成目前仅适用于 TiDB Cloud Dedicated 集群。
  • 当集群状态为 CREATING、RESTORING、PAUSED 或 RESUMING 时，不支持 Prometheus 和 Grafana 集成。

步骤

步骤 1. 获取 Prometheus 的 scrape_config 文件

在配置 Prometheus 服务以读取 TiDB Cloud 统计/指标（信息）之前，你需要先在 TiDB Cloud 中生成一个 scrape_config YAML 文件。该 scrape_config 文件包含一个唯一的 bearer token，允许 Prometheus 服务监控你的目标 TiDB Cloud Dedicated 集群。

根据你的 Prometheus 集成版本，获取 Prometheus 的 scrape_config 文件及访问集成页面的步骤有所不同。

    1. 在 TiDB Cloud 控制台中，导航到 My TiDB 页面，然后点击目标 TiDB Cloud Dedicated 集群的名称进入其概览页面。
    2. 在左侧导航栏，点击 Settings > Integrations。
    3. 在 Integrations 页面，点击 Integration to Prometheus。
    4. 点击 Add File，为当前集群生成并显示 scrape_config 文件。
    5. 复制 scrape_config 文件内容，供后续使用。
    1. 在 TiDB Cloud 控制台中，导航到组织的 My TiDB 页面，然后点击 Project view 标签页。
    2. 在项目视图中，找到目标项目，然后点击该项目的 。
    3. 在左侧导航栏，点击 Project Settings 下的 Integrations。
    4. 在 Integrations 页面，点击 Integration to Prometheus (BETA)。
    5. 点击 Add File，为当前项目生成并显示 scrape_config 文件。
    6. 复制 scrape_config 文件内容，供后续使用。

    步骤 2. 集成 Prometheus

    1. 在你的 Prometheus 服务指定的监控目录中，找到 Prometheus 配置文件。

      例如：/etc/prometheus/prometheus.yml。

    2. 在 Prometheus 配置文件中，找到 scrape_configs 部分，然后将从 TiDB Cloud 获取的 scrape_config 文件内容复制到该部分。

    3. 在 Prometheus 服务中，检查 Status > Targets，确认新的 scrape_config 文件已被读取。如果未生效，可能需要重启 Prometheus 服务。

    步骤 3. 使用 Grafana GUI 仪表盘可视化统计/指标（信息）

    当你的 Prometheus 服务已从 TiDB Cloud 读取统计/指标（信息）后，可以通过 Grafana GUI 仪表盘进行可视化，操作如下：

    1. 根据你的 Prometheus 集成版本，下载 TiDB Cloud for Prometheus 的 Grafana 仪表盘 JSON 文件的链接不同。

      • 对于集群级 Prometheus 集成，请在 此处 下载 Grafana 仪表盘 JSON 文件。
      • 对于遗留项目级 Prometheus 集成（Beta），请在 此处 下载 Grafana 仪表盘 JSON 文件。

    2. 将该 JSON 导入到你自己的 Grafana GUI，以可视化统计/指标（信息）。

    3. （可选）根据需要自定义仪表盘，例如添加或移除面板、修改数据源、调整显示选项等。

    关于如何使用 Grafana 的更多信息，请参见 Grafana 官方文档。

    scrape_config 轮转最佳实践

    为提升数据安全性，建议定期轮转 scrape_config 文件的 bearer token。

    1. 按照 步骤 1 为 Prometheus 创建新的 scrape_config 文件。
    2. 将新文件内容添加到 Prometheus 配置文件中。
    3. 确认 Prometheus 服务仍能从 TiDB Cloud 读取后，从 Prometheus 配置文件中移除旧的 scrape_config 文件内容。
    4. 在项目或集群的 Integrations 页面，删除对应的旧 scrape_config 文件，防止他人利用其读取 TiDB Cloud Prometheus 端点。

    Prometheus 可用统计/指标（信息）

    Prometheus 会跟踪你的 TiDB 集群的以下统计/指标（信息）数据。

    统计/指标（信息）名称统计/指标（信息）类型标签描述
    tidbcloud_db_queries_totalcountsql_type: Select\|Insert\|...
    cluster_name: <cluster name>
    instance: tidb-0\|tidb-1…
    component: tidb    		执行的语句总数
    tidbcloud_db_failed_queries_totalcounttype: planner:xxx\|executor:2345\|...
    cluster_name: <cluster name>
    instance: tidb-0\|tidb-1…
    component: tidb    		执行错误总数
    tidbcloud_db_connectionsgaugecluster_name: <cluster name>
    instance: tidb-0\|tidb-1…
    component: tidb    		当前 TiDB server 的连接数
    tidbcloud_db_query_duration_secondshistogramsql_type: Select\|Insert\|...
    cluster_name: <cluster name>
    instance: tidb-0\|tidb-1…
    component: tidb    		语句的耗时直方图
    tidbcloud_changefeed_latencygaugechangefeed_idchangefeed 上游与下游间的数据同步延时
    tidbcloud_changefeed_checkpoint_tsgaugechangefeed_idchangefeed 的 checkpoint 时间戳，表示已成功写入下游的最大 TSO（Timestamp Oracle）
    tidbcloud_changefeed_replica_rowsgaugechangefeed_idchangefeed 每秒写入下游的同步行数
    tidbcloud_node_storage_used_bytesgaugecluster_name: <cluster name>
    instance: tikv-0\|tikv-1…\|tiflash-0\|tiflash-1…
    component: tikv\|tiflash    		TiKV 或 TiFlash 节点的磁盘使用量（字节）。该统计/指标（信息）主要表示存储引擎中的逻辑数据大小，不包含 WAL 文件和临时文件。实际磁盘使用率建议用 (capacity - available) / capacity 计算。当 TiKV 存储使用率超过 80% 时，可能出现延时激增，使用率更高时可能导致请求失败。当所有 TiFlash 节点存储使用率达到 80% 时，任何添加 TiFlash 副本的 DDL 语句将会假死。
    tidbcloud_node_storage_capacity_bytesgaugecluster_name: <cluster name>
    instance: tikv-0\|tikv-1…\|tiflash-0\|tiflash-1…
    component: tikv\|tiflash    		TiKV/TiFlash 节点的磁盘容量（字节）
    tidbcloud_node_cpu_seconds_totalcountcluster_name: <cluster name>
    instance: tidb-0\|tidb-1…\|tikv-0…\|tiflash-0…
    component: tidb\|tikv\|tiflash    		TiDB/TiKV/TiFlash 节点的 CPU 使用量
    tidbcloud_node_cpu_capacity_coresgaugecluster_name: <cluster name>
    instance: tidb-0\|tidb-1…\|tikv-0…\|tiflash-0…
    component: tidb\|tikv\|tiflash    		TiDB/TiKV/TiFlash 节点的 CPU 限制核数
    tidbcloud_node_memory_used_bytesgaugecluster_name: <cluster name>
    instance: tidb-0\|tidb-1…\|tikv-0…\|tiflash-0…
    component: tidb\|tikv\|tiflash    		TiDB/TiKV/TiFlash 节点的已用内存（字节）
    tidbcloud_node_memory_capacity_bytesgaugecluster_name: <cluster name>
    instance: tidb-0\|tidb-1…\|tikv-0…\|tiflash-0…
    component: tidb\|tikv\|tiflash    		TiDB/TiKV/TiFlash 节点的内存容量（字节）
    tidbcloud_node_storage_available_bytesgaugeinstance: tidb-0\|tidb-1\|...
    component: tikv\|tiflash
    cluster_name: <cluster name>    		TiKV/TiFlash 节点可用磁盘空间（字节）
    tidbcloud_disk_read_latencyhistograminstance: tidb-0\|tidb-1\|...
    component: tikv\|tiflash
    cluster_name: <cluster name>
    device: nvme.*\|dm.*    		每个存储设备的读延时（秒）
    tidbcloud_disk_write_latencyhistograminstance: tidb-0\|tidb-1\|...
    component: tikv\|tiflash
    cluster_name: <cluster name>
    device: nvme.*\|dm.*    		每个存储设备的写延时（秒）
    tidbcloud_kv_request_durationhistograminstance: tidb-0\|tidb-1\|...
    component: tikv
    cluster_name: <cluster name>
    type: BatchGet\|Commit\|Prewrite\|...    		TiKV 各类型请求的耗时（秒）
    tidbcloud_component_uptimehistograminstance: tidb-0\|tidb-1\|...
    component: tidb\|tikv\|tiflash
    cluster_name: <cluster name>    		TiDB 组件的运行时长（秒）
    tidbcloud_ticdc_owner_resolved_ts_laggaugechangefeed_id: <changefeed-id>
    cluster_name: <cluster name>    		changefeed owner 的 resolved timestamp 延迟（秒）
    tidbcloud_changefeed_statusgaugechangefeed_id: <changefeed-id>
    cluster_name: <cluster name>    		changefeed 状态：
    -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>    		Resource Manager 消耗的读请求单元
    tidbcloud_resource_manager_resource_unit_write_request_unitgaugecluster_name: <cluster name>
    resource_group: <group-name>    		Resource Manager 消耗的写请求单元

    对于集群级 Prometheus 集成，还可获取以下额外统计/指标（信息）：

    统计/指标（信息）名称统计/指标（信息）类型标签描述
    tidbcloud_dm_task_statusgaugeinstance: instance
    task: task
    cluster_name: <cluster name>    		数据迁移任务状态：
    0: Invalid
    1: New
    2: Running
    3: Paused
    4: Stopped
    5: Finished
    15: Error
    tidbcloud_dm_syncer_replication_lag_bucketgaugeinstance: instance
    cluster_name: <cluster name>    		数据迁移的同步延迟（bucket）
    tidbcloud_dm_syncer_replication_lag_gaugegaugeinstance: instance
    task: task
    cluster_name: <cluster name>    		数据迁移的同步延迟（gauge）
    tidbcloud_dm_relay_read_error_countcountinstance: instance
    cluster_name: <cluster name>    		从主库读取 binlog 失败的次数

    常见问题

    • 为什么同一统计/指标（信息）在 Grafana 和 TiDB Cloud 控制台上同时显示的数值不同？

      Grafana 与 TiDB Cloud 的聚合计算逻辑不同，因此显示的聚合值可能存在差异。你可以在 Grafana 中调整 mini step 配置，以获得更细粒度的统计/指标（信息）值。

    文档内容是否有帮助？