对于数据库系统来说，经常会遇到需要远程定位问题或快速检查集群状态的情况。TiDB 数据库中提供一个称之为 Clinic 诊断服务 的功能，其主要用途就是为 TiDB 集群提供诊断服务，可以借此对集群进行远程定位集群问题和本地快速检查集群状态。

Clinic 的构成

Clinic 是一个诊断服务，它主要包含 2 个组件：

Diag 诊断客户端。这是一个部署在集群端的开源工具，用于采集诊断数据、上传诊断数据到 Clinic Server、对集群进行本地快速健康检查。Diag 当前内置在 tiup 中，可通过 tiup 一键安装。
Clinic Server。部署在云端的服务。通过 Diag 上传的诊断数据，提供在线诊断能力，并提供诊断报告。根据数据存储位置不同，分为 Clinic Server 中国区和 Clinic Server 美国区，分别对应 AWS 中国区和 AWS 美国区。

Clinic 采集诊断数据的工作原理

Clinic 主要工作分为 2 块，即使用 Diag 客户端收集数据及使用 Clinic Server 端分析数据。这其中比较重要的是 Diag 会收集哪些数据以及怎么收集，简单来说，Diag 收集数据的流程如下：

从 TiUP 或 TiDB Operator 获取集群拓扑信息。
通过 SCP 传输服务器文件，如日志文件和配置文件等。
通过 SSH 远程执行命令采集数据，如内核日志、内核参数、硬件基础信息等。
通过 HTTP 调用采集数据，通过调用 TiDB 组件的 HTTP 接口获取 TiDB/TiKV/PD 等组件配置采样信息与性能采集信息，通过调用 Prometheus 的 HTTP 接口获取报警信息和 metrics 监控数据。
通过 SQL 语句查询数据库参数，对此需要额外提供访问数据库用户和密码。

如何使用 Clinic 诊断服务

以下步骤简单描述如何使用使用 Clinic 诊断服务来收集诊断服务并生成诊断报告。

首先，要确保在安装 TiUP 中控机上安装 Diag，如果未安装，则使用 tiup install diag 安装。

tiup install diag
tiup list diag

登录 Clinic Server，获取用于上传数据的 Access Token。如果之前未创建组织(Org)，则需要先创建一个 Org。如果已经有 Org，则进入此 Org 并在右下角找到 Get Access Token For Diag Tool 获取 Token。

在 Diag 中设置 Token 和 Region，命令如下所示，其中 ${token-string} 使用上述实际 Token 替换。

tiup diag config clinic.token ${token-string}
tiup diag config clinic.region CN

运行 Diag 采集诊断数据。使用 diag collect 命令收集，至少需要指定集群名称和采集时间范围。执行命令后会打印所有需要收集的内容，这些文件会统一存放在/home/tidb/diag-<clustername>-XXX 目录。

[tidb@host151 ~]$ tiup diag collect tidb-ee -f="-2h" -t="-1h"
tiup is checking updates for component diag ...
Starting component `diag`: /home/tidb/.tiup/components/diag/v1.5.0/diag collect tidb-ee -f=-2h -t=-1h
Detecting metadata of the cluster...

Detecting alert lists from Prometheus node...

Detecting metrics from Prometheus node...

Detecting basic system information of servers...

Detecting logs of components...

+ Download necessary tools

+ Collect host information

Detecting config files of components...

+ Collect host information


Time range:
  2024-07-24T09:41:47+08:00 - 2024-07-24T10:41:47+08:00 (Local)
  2024-07-24T01:41:47Z - 2024-07-24T02:41:47Z (UTC)
  (total 3600 seconds)

Estimated size of data to collect:
Host               Size                Target
----               ----                ------
10.xx.x.151:19095  28.75 MB   2538 metrics, compressed
xx.xx.x.152        221.88 MB  /data1/tidb-ee-deploy/tidb-14000/log/tidb.log
xx.xx.x.152        36.18 MB   /data1/tidb-ee-deploy/tidb-14000/log/tidb_stderr.log
xx.xx.x.152        202.83 MB  /data1/tidb-ee-deploy/pd-12379/log/pd.log
xx.xx.x.152        403.62 kB  /data1/tidb-ee-deploy/pd-12379/log/pd_stderr.log
xx.xx.x.152        218.32 MB  /data1/tidb-ee-deploy/tikv-30160/log/tikv.log
xx.xx.x.152        0 B        /data1/tidb-ee-deploy/tikv-30160/log/tikv_stderr.log
xx.xx.x.152        11.14 MB   /data1/tidb-ee-deploy/tidb-14000/log/tidb-audit.log
xx.xx.x.153        18.00 MB   /data1/tidb-ee-deploy/tidb-14000/log/tidb-audit.log
xx.xx.x.153        243.76 MB  /data1/tidb-ee-deploy/tidb-14000/log/tidb.log
xx.xx.x.153        21.24 MB   /data1/tidb-ee-deploy/tidb-14000/log/tidb_stderr.log
xx.xx.x.153        34.09 MB   /data1/tidb-ee-deploy/pd-12379/log/pd.log
xx.xx.x.153        9.27 MB    /data1/tidb-ee-deploy/pd-12379/log/pd_stderr.log
xx.xx.x.153        54.45 MB   /data1/tidb-ee-deploy/tikv-30160/log/tikv.log
xx.xx.x.153        0 B        /data1/tidb-ee-deploy/tikv-30160/log/tikv_stderr.log
xx.xx.x.155        537.30 MB  /data1/tidb-ee-deploy/tiflash-9000/log/tiflash.log
xx.xx.x.155        628 B      /data1/tidb-ee-deploy/tiflash-9000/log/tiflash_stderr.log
xx.xx.x.155        61.69 MB   /data1/tidb-ee-deploy/tiflash-9000/log/tiflash_tikv.log
xx.xx.x.154        579.32 MB  /data1/tidb-ee-deploy/tiflash-9000/log/tiflash.log
xx.xx.x.154        628 B      /data1/tidb-ee-deploy/tiflash-9000/log/tiflash_stderr.log
xx.xx.x.154        61.42 MB   /data1/tidb-ee-deploy/tiflash-9000/log/tiflash_tikv.log
xx.xx.x.151        39.52 MB   /data1/tidb-ee-deploy/tidb-14000/log/tidb_stderr.log
xx.xx.x.151        256.21 MB  /data1/tidb-ee-deploy/tikv-30160/log/tikv.log
xx.xx.x.151        42.93 MB   /data1/tidb-ee-deploy/tidb-14000/log/tidb-audit.log
xx.xx.x.151        22.94 MB   /data1/tidb-ee-deploy/prometheus-19095/log/ng.log
xx.xx.x.151        74.47 MB   /data1/tidb-ee-deploy/pd-12379/log/pd.log
xx.xx.x.151        6.21 MB    /data1/tidb-ee-deploy/pd-12379/log/pd_stderr.log
xx.xx.x.151        146.72 MB  /data1/tidb-ee-deploy/tidb-14000/log/tidb.log
xx.xx.x.151        4.89 MB    /data1/tidb-ee-deploy/prometheus-19095/log/prometheus.log
xx.xx.x.151        0 B        /data1/tidb-ee-deploy/tikv-30160/log/tikv_stderr.log
xx.xx.x.153        1.64 kB    /data1/tidb-ee-deploy/tidb-14000/conf/tidb-server-key.pem
xx.xx.x.153        1.70 kB    /data1/tidb-ee-deploy/tidb-14000/conf/tidb-server.pem
xx.xx.x.153        355 B      /data1/tidb-ee-deploy/tidb-14000/conf/tidb.toml
xx.xx.x.153        323 B      /data1/tidb-ee-deploy/pd-12379/conf/pd.toml
xx.xx.x.153        521 B      /data1/tidb-ee-deploy/tikv-30160/conf/tikv.toml
xx.xx.x.153        2.11 kB    /data1/tidb-ee-deploy/tidb-14000/conf/ca.pem
xx.xx.x.155        776 B      /data1/tidb-ee-deploy/tiflash-9000/conf/tiflash-learner.toml
xx.xx.x.155        1.26 kB    /data1/tidb-ee-deploy/tiflash-9000/conf/tiflash.toml
xx.xx.x.152        521 B      /data1/tidb-ee-deploy/tikv-30160/conf/tikv.toml
xx.xx.x.152        2.11 kB    /data1/tidb-ee-deploy/tidb-14000/conf/ca.pem
xx.xx.x.152        1.64 kB    /data1/tidb-ee-deploy/tidb-14000/conf/tidb-server-key.pem
xx.xx.x.152        1.70 kB    /data1/tidb-ee-deploy/tidb-14000/conf/tidb-server.pem
xx.xx.x.152        355 B      /data1/tidb-ee-deploy/tidb-14000/conf/tidb.toml
xx.xx.x.152        323 B      /data1/tidb-ee-deploy/pd-12379/conf/pd.toml
xx.xx.x.154        1.26 kB    /data1/tidb-ee-deploy/tiflash-9000/conf/tiflash.toml
xx.xx.x.154        776 B      /data1/tidb-ee-deploy/tiflash-9000/conf/tiflash-learner.toml
xx.xx.x.151        1.64 kB    /data1/tidb-ee-deploy/tidb-14000/conf/tidb-server-key.pem
xx.xx.x.151        1.70 kB    /data1/tidb-ee-deploy/tidb-14000/conf/tidb-server.pem
xx.xx.x.151        355 B      /data1/tidb-ee-deploy/tidb-14000/conf/tidb.toml
xx.xx.x.151        323 B      /data1/tidb-ee-deploy/pd-12379/conf/pd.toml
xx.xx.x.151        521 B      /data1/tidb-ee-deploy/tikv-30160/conf/tikv.toml
xx.xx.x.151        2.11 kB    /data1/tidb-ee-deploy/tidb-14000/conf/ca.pem
Total              2.87 GB    (inaccurate)
These data will be stored in /home/tidb/diag-tidb-ee-gsF2Jd8Q28F
Do you want to continue? [y/N]: (default=N)

根据上述输出显示，待收集数据大小为 2.87 GB，数据收集存放路径 /home/tidb/diag-tidb-ee-gsF2Jd8Q28F 。确认收集后会开始进行自动化收集的动作，根据数据大小时间不等。

查看诊断数据目录。目录中包括meta.yaml 文件(集群元信息)、cluster.json 文件(集群拓扑信息)、diag 日志文件、monitor 子目录(监控数据)及节点子目录(各组件日志文件和配置信息、操作系统和硬件基础信息和配置信息)。

[tidb@host-10-17-3-151 diag-tidb-ee-gsF2Jd8Q28F]$ ls -lrt
总用量 14656
-rw-rw-r-- 1 tidb tidb     5580  7月 24 12:49 meta.yaml
-rw-rw-r-- 1 tidb tidb    22832  7月 24 12:49 cluster.json
drwxr-xr-x 4 tidb tidb       35  7月 24 12:49 monitor
drwxr-xr-x 3 tidb tidb      108  7月 24 12:50 xx.xx.x.155
drwxr-xr-x 3 tidb tidb      108  7月 24 12:50 xx.xx.x.153
drwxr-xr-x 3 tidb tidb      108  7月 24 12:50 xx.xx.x.151
drwxr-xr-x 3 tidb tidb      108  7月 24 12:50 xx.xx.x.154
drwxr-xr-x 3 tidb tidb      108  7月 24 12:50 xx.xx.x.152
-rw-rw-r-- 1 tidb tidb 14971473  7月 24 13:00 gsF7XKM3KtD_diag_audit.log

[tidb@host-10-17-3-151 diag-tidb-ee-gsF2Jd8Q28F]$ tree monitor/
monitor/
├── alerts
│   └── 10.17.3.151-19095
│       └── alerts.json
└── metrics
    └── 10.17.3.151-19095
        ├── ALERTS_2024-07-24T09:41:47+08:00_2024-07-24T10:41:47+08:00.json
        ├── ALERTS_FOR_STATE_2024-07-24T09:41:47+08:00_2024-07-24T10:41:47+08:00.json
        ├── br_raw_backup_region_seconds_bucket_2024-07-24T09:41:47+08:00_2024-07-24T10:41:47+08:00.json
        ├── br_raw_backup_region_seconds_count_2024-07-24T09:41:47+08:00_2024-07-24T10:41:47+08:00.json
...

[tidb@host-10-17-3-151 diag-tidb-ee-gsF2Jd8Q28F]$ tree xx.xx.x.151
xx.xx.x.151
├── data1
│   └── tidb-ee-deploy
│       ├── pd-12379
│       │   ├── conf
│       │   │   ├── config.json
│       │   │   ├── pd.toml
│       │   │   ├── placement-rule.json
│       │   │   └── store.json
│       │   └── log
│       │       ├── pd.log
│       │       └── pd_stderr.log
│       ├── prometheus-19095
│       │   └── log
│       │       ├── ng.log
│       │       └── prometheus.log
│       ├── tidb-14000
│       │   ├── conf
│       │   │   ├── ca.pem
│       │   │   ├── config.json
│       │   │   ├── tidb-server-key.pem
│       │   │   ├── tidb-server.pem
│       │   │   └── tidb.toml
│       │   └── log
│       │       ├── tidb-audit.log
│       │       ├── tidb.log
│       │       └── tidb_stderr.log
│       └── tikv-30160
│           ├── conf
│           │   ├── config.json
│           │   └── tikv.toml
│           └── log
│               ├── tikv.log
│               └── tikv_stderr.log
├── dmesg.log
├── insight.json
├── limits.conf
├── ss.txt
└── sysctl.conf

13 directories, 25 files

上传诊断数据到 Clinic Server。判断集群能否连接外网，如果可以，则直接通过 diag upload 命令上传文件即可。如果无法连接外网，则需要使用 diag package 命令将目录打成 .diag 压缩包方式，将压缩包发到有网络的机器上进行上传。以下输出表示 dia upload 会将目录压缩成 .diag 包并上传到网络，由于网络不通，upload 失败。

[tidb@host151 ~]$ tiup diag upload /home/tidb/diag-tidb-ee-gsF2Jd8Q28F
tiup is checking updates for component diag ...
Starting component `diag`: /home/tidb/.tiup/components/diag/v1.5.0/diag upload /home/tidb/diag-tidb-ee-gsF2Jd8Q28F
packaging collected data...

Error: preupload file failed, error is Post "https://clinic.pingcap.com.cn/clinic/api/v1/diag/precreate?alias=&compression=none&encryption=diag&filename=diag-tidb-ee-gsF2Jd8Q28F.diag&length=160753183&uuid=376cd97c50fa2a64-37cd25209dc34e04-81d923dc3f4c98c4": dial tcp 71.132.12.117:443: i/o timeout

Verbose debug logs has been written to /home/tidb/.tiup/logs/tiup-diag-debug-2024-07-24-13-53-59.log.

在 Clinic Server 上直接上传 .diag 文件。如果网络不通，将 .diag 下载下来后，从有网络的上机器上打开网页登录 Clinic Server，并点击右下角 Upload Diag Package，上传 .diag 文件。

如上图所示，上传之后点击进入可以查看到集群的基本信息、诊断时间范围、Details、Reports。Details 部分具体包括 Metrics(可查看相应的 Grafana 图表)、Instance Logs(可查看相应的组件日志文件)、Slow Query(可查看时间段内慢SQL)、Download Data(可下载诊断数据到本地)。有关详细采集信息，可参考官网文档 PingCAP Clinic 数据采集说明

采集数据的参数说明

上述示例中采集数据使用比较简单的 tiup diag collect tidb-ee -f="-2h" -t="-1h" 命令执行，此命令默认会收集当前时间点往前2小时~1小时之间的所有数据。然而有时候我们可能想自定义收集数据，比如只收集指定节点的数据、只收集特定类型的数据等。通过 diag collect -h 可以查看所有支持的参数，使用较多的参数包括：

-l：传输文件时的带宽限制，单位为 Kbit/s，默认值为 100000（即 scp 的 -l 参数）。
-N/--node：支持只收集指定节点的数据，格式为 ip:port。
--include：只收集特定类型的数据，可选值为 system，monitor，log，config，db_vars。如需同时列出多种类型的数据，你可以使用逗号 , 来分割不同的数据类型。
--exclude：不收集特定类型的数据，可选值为 system，monitor，log，config，db_vars。如需同时列出多种类型的数据，你可以使用逗号 , 来分割不同的数据类型。

另外，对于时间范围的参数 -f 和 -t，具体包含如下：

-f/--from：指定采集时间的起始点。如果不指定该参数，默认起始点为当前时间的 2 小时前。如需修改时区，可使用 -f="12:30 +0800" 语法。如果没有在该参数中指定时区信息，如 +0800，则默认时区为 UTC。
-t/--to：指定采集时间的结束点。如果不指定该参数，默认结束点为当前时刻。如需修改时区，可使用 -f="12:30 +0800" 语法。如果没有在该参数中指定时区信息，如 +0800，则默认时区为 UTC。

以下示例命令的含义表示，收集 xx.xx.x.153:30160 这个特定 TiKV 组件的、时间范围在 2024-07-22T11:00:00~2024-07-22T12:00:00 的、只包含 log 日志的诊断数据。

tiup diag collect tidb-ee -f="2024-07-22T11:00:00+08:00" -t="2024-07-22T12:00:00+08:00" -N="xx.xx.x.153:30160" --include="log"

总结与补充

本文简单整理并介绍 PingCAP Clinic 诊断服务的概念及用法，读者应能据此了解如何使用 Clinic 进行诊断信息收集并上传分析。根据收集的诊断数据，Clinic Server 不仅可以帮助远程分析问题，还能够生成诊断报告，包括 Benchmark Report 和 Comparison Report，用于在特定场景下检查集群健康风险，并协助定位集群问题，本文对诊断报告相关内容未作详细说明，读者可参考 TiDB 官网文档使用 PingCAP Clinic 生成诊断报告。

另外，TiDB 自 v5.3 版本中引入 PLAN REPLAYER 命令，用于快速保存和恢复查询计划相关的信息，简化了排查优化器相关问题时提取排查信息的步骤。Clinic Diag 也集成了 PLAN REPLAYER，可以使用 Diag 快捷的保存查询计划相关的数据，可参考使用 PingCAP Clinic Diag 采集 SQL 查询计划信息获取详细信息。

一文了解 PingCAP Clinic 诊断服务

Clinic 的构成

Clinic 采集诊断数据的工作原理

如何使用 Clinic 诊断服务

采集数据的参数说明

总结与补充