📣
TiDB Cloud Essential 开放公测中。此页面由 AI 自动翻译，英文原文请见此处。
TiDB Cloud
TiDB
社区
联系我们

集成 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 集成（预览版）。

  • 集群级 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 项目下的目标集群。

限制

  • 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 服务监控你的目标集群。

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

    1. 在 TiDB Cloud 控制台中，进入你项目的 Clusters 页面，然后点击目标集群名称进入其概览页面。
    2. 在左侧导航栏，点击 Settings > Integrations。
    3. 在 Integrations 页面，点击 Integration to Prometheus (Preview)。
    4. 点击 Add File，为当前集群生成并显示 scrape_config 文件。
    5. 复制 scrape_config 文件内容，供后续使用。
    1. 在 TiDB Cloud 控制台中，使用左上角的下拉框切换到目标项目。
    2. 在左侧导航栏，点击 Project Settings > Integrations。
    3. 在 Integrations 页面，点击 Integration to Prometheus (BETA)。
    4. 点击 Add File，为当前项目生成并显示 scrape_config 文件。
    5. 复制 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 服务器的连接数
    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 的检查点时间戳，表示已成功写入下游的最大 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 节点的磁盘已用字节数
    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: 未知
    0: 正常
    1: 警告
    2: 失败
    3: 已停止
    4: 已完成
    6: 警告
    7: 其他
    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: 无效
    1: 新建
    2: 运行中
    3: 暂停
    4: 停止
    5: 完成
    15: 错误
    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 配置，以获得更细粒度的指标值。

    文档内容是否有帮助？

    文档反馈社区交流