Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

add content for clinic us server #9566

Merged
merged 8 commits into from
Jul 15, 2022
Merged

add content for clinic us server #9566

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
eed4e2b
add clinic server in us
Oreoxmt Jul 14, 2022
88966ba
Update clinic/clinic-introduction.md
Oreoxmt Jul 14, 2022
0470add
Update clinic/clinic-introduction.md
Oreoxmt Jul 14, 2022
5ceac2f
Update clinic/clinic-introduction.md
Oreoxmt Jul 14, 2022
73072d0
put the US server first
Oreoxmt Jul 14, 2022
a8a4ebf
add regions
Oreoxmt Jul 14, 2022
9becc23
apply suggestions from code review
Oreoxmt Jul 15, 2022
e7622a3
fix typo
Oreoxmt Jul 15, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion TOC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -332,7 +332,7 @@
- [tiup-cluster](/tiup/tiup-cluster.md)
- [tiup-mirror](/tiup/tiup-mirror.md)
- [tiup-bench](/tiup/tiup-bench.md)
- PingCAP Clinic Diagnostic Service (Technical Preview)
- PingCAP Clinic Diagnostic Service
- [Overview](/clinic/clinic-introduction.md)
- [Quick Start](/clinic/quick-start-with-clinic.md)
- [Troubleshoot TiDB Cluster Using PingCAP Clinic](/clinic/clinic-user-guide-for-tiup.md)
Expand Down
7 changes: 3 additions & 4 deletions clinic/clinic-data-instruction-for-tiup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,10 @@ This document provides the types of diagnostic data that can be collected by Pin

The diagnostic data collected by PingCAP Clinic is **only** used for troubleshooting cluster problems.

Clinic Server is a diagnostic service deployed in the cloud. Currently, you can upload the collected diagnostic data to [Clinic Server China](https://clinic.pingcap.com.cn) only. The uploaded data is stored in the AWS S3 China (Beijing) region server set up by PingCAP. Clinic Server Global will be provided soon with a new URL and data storage location. For details, see [PingCAP Clinic components](/clinic/clinic-introduction.md).
Clinic Server is a diagnostic service deployed in the cloud. There are two independent services bases on different storage location:
shichun-0415 marked this conversation as resolved.
Show resolved Hide resolved

PingCAP strictly controls permissions for data access and only allows authorized in-house technical support staff to access the uploaded data.

After a technical support case is closed, PingCAP permanently deletes or anonymizes the corresponding data within 90 days.
- [Clinic Server in Chinese mainland](https://clinic.pingcap.com.cn): If you upload the collected data to Clinic Server in Chinese mainland, the data will be stored in the Amazon S3 set up by PingCAP in AWS China (Beijing). PingCAP strictly controls permissions for data and only allows authorized technical support staffs to access the data.
- [Clinic Server in US](https://clinic.pingcap.com): If you upload the collected data to Clinic Server in US, the data will be stored in the Amazon S3 set up by PingCAP in AWS US. PingCAP strictly controls permissions for data and only allows authorized technical support staffs to access the data.

## TiDB clusters

Expand Down
28 changes: 22 additions & 6 deletions clinic/clinic-introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,31 +7,32 @@ summary: Learn about the PingCAP Clinic Diagnostic Service (PingCAP Clinic), inc

PingCAP Clinic Diagnostic Service (PingCAP Clinic) is a diagnostic service provided by PingCAP for TiDB clusters that are deployed using either TiUP or TiDB Operator. This service helps to troubleshoot cluster problems remotely and provides a quick check of cluster status locally. With PingCAP Clinic, you can ensure the stable operation of your TiDB cluster for its full life-cycle, predict potential problems, reduce the probability of problems, troubleshoot cluster problems quickly, and fix cluster problems.

PingCAP Clinic is currently in the Technical Preview stage. This service provides the following two components to diagnose cluster problems:
PingCAP Clinic provides the following two components to diagnose cluster problems:

- Diag client:

Diag client (Diag) is a diagnostic tool deployed on the cluster side. Diag is used to collect cluster diagnostic data, upload diagnostic data to the Clinic Server, and perform a quick health check locally on your cluster. For a full list of diagnostic data that can be collected by Diag, see [PingCAP Clinic Diagnostic Data](/clinic/clinic-data-instruction-for-tiup.md).

> **Note:**
>
> Diag temporarily **does not support** collecting data from the clusters deployed using TiDB Ansible.
> Diag supports TiDB v4.0 and later versions, but **does not support** collecting data from the clusters deployed using TiDB Ansible.
shichun-0415 marked this conversation as resolved.
Show resolved Hide resolved

- Clinic Server:

Clinic Server is a cloud service deployed in the cloud. By providing diagnostic services in the SaaS model, the Clinic Server can not only receive uploaded diagnostic data but also work as an online diagnostic environment to store data, view data, and provide cluster diagnostic reports.
Clinic Server is a cloud service deployed in the cloud. By providing diagnostic services in the SaaS model, the Clinic Server can not only receive uploaded diagnostic data but also work as an online diagnostic environment to store data, view data, and provide cluster diagnostic reports. There are two independent services based on different storage locations:
shichun-0415 marked this conversation as resolved.
Show resolved Hide resolved

Currently, you can upload the collected diagnostic data to [Clinic Server China](https://clinic.pingcap.com.cn) only. The uploaded data is stored in the AWS S3 China (Beijing) region server set up by PingCAP. Clinic Server Global will be provided soon with a new URL and data storage location in one of the AWS S3 regions in North America.
- [Clinic Server in Chinese mainland](https://clinic.pingcap.com.cn): the collected data is stored in AWS China (Beijing).
- [Clinic Server in US](https://clinic.pingcap.com): the collected data is stored in AWS US.

## User scenarios

- Troubleshoot cluster problems remotely

When your cluster has some problems that cannot be fixed quickly, you can ask for help at [TiDB Community slack channel](https://tidbcommunity.slack.com/archives/CH7TTLL7P) or contact PingCAP technical support. When contacting technical support for remote assistance, you need to save various diagnostic data from the cluster and forward the data to the support staff. In this case, you can use Diag to collect diagnostic data with one click. Diag helps you to collect complete diagnostic data quickly, which can avoid complex manual data collection operations. After collecting data, you can upload the data to the Clinic Server for PingCAP technical support staff to troubleshoot cluster problems. The Clinic Server provides secure storage for uploaded diagnostic data and supports the online diagnosis, which greatly improves the troubleshooting efficiency.

- Perform a quick check on the cluster status locally
- Perform a quick check on the cluster status
shichun-0415 marked this conversation as resolved.
Show resolved Hide resolved

Even if your cluster runs stably now, it is necessary to periodically check the cluster to avoid potential stability risks. You can check the potential health risks of a cluster using the local quick check feature provided by PingCAP Clinic. The PingCAP Clinic Technical Preview version provides a rationality check on cluster configuration items to discover unreasonable configurations and provide modification suggestions.
Even if your cluster runs stably now, it is necessary to periodically check the cluster to avoid potential stability risks. You can check the potential health risks of a cluster using the local and remote quick check feature provided by PingCAP Clinic.
Oreoxmt marked this conversation as resolved.
Show resolved Hide resolved

## Implementation principles

Expand All @@ -56,6 +57,21 @@ First, Diag gets cluster topology information from the deployment tool TiUP (tiu

Using SQL statements, Diag can query system variables and other information of TiDB. To use this method, you need to **additionally provide** the username and password to access TiDB when collecting data.

## The limitations of Clinic Server

> **Note:**
>
> - Clinic Server provides free service from July 15, 2022 to Jan 14, 2023. PingCAP Clinic will notify you through email before Jan 14, 2023 if the service starts requiring payment.
shichun-0415 marked this conversation as resolved.
Show resolved Hide resolved
> - If you want to adjust the usage limitations, contact PingCAP technical support.

| Service Type| Limitation |
| :------ | :------ |
| Number of clusters | 10/organization |
| Storage capacity | 50 GB/cluster |
| Storage time | 180 days |
shichun-0415 marked this conversation as resolved.
Show resolved Hide resolved
| Data size | 3 GB |
Oreoxmt marked this conversation as resolved.
Show resolved Hide resolved
| Saving time | 3 days|
Oreoxmt marked this conversation as resolved.
Show resolved Hide resolved

## Next step

- Use PingCAP Clinic in an on-premise environment
Expand Down
102 changes: 62 additions & 40 deletions clinic/clinic-user-guide-for-tiup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,13 @@ summary: Learn how to use the PingCAP Clinic Diagnostic Service to troubleshoot

# Troubleshoot TiDB Cluster Using PingCAP Clinic

For TiDB clusters and DM clusters deployed using TiUP, you can use PingCAP Clinic Diagnostic Service (PingCAP Clinic) to troubleshoot cluster problems remotely and perform a quick check on cluster status locally using Diag client (Diag) and [Clinic Server China](https://clinic.pingcap.com.cn) (Clinic Server). For details about Diag and Clinic Server, see [PingCAP Clinic components](/clinic/clinic-introduction.md).

PingCAP Clinic is currently in the Technical Preview stage.
For TiDB clusters and DM clusters deployed using TiUP, you can use PingCAP Clinic Diagnostic Service (PingCAP Clinic) to troubleshoot cluster problems remotely and perform a quick check on cluster status locally using Diag client (Diag) and Clinic Server. For details about Diag and Clinic Server, see [PingCAP Clinic components](/clinic/clinic-introduction.md).
shichun-0415 marked this conversation as resolved.
Show resolved Hide resolved

> **Note:**
>
> PingCAP Clinic **does not support** collecting data from the clusters deployed using TiDB Ansible.
> - This document **only** applies to clusters deployed using TiUP in an on-premises environment. For clusters deployed using TiDB Operator in Kubernetes, see [PingCAP Clinic for TiDB Operator environments](https://docs.pingcap.com/tidb-in-kubernetes/stable/clinic-user-guide).
>
> - PingCAP Clinic **does not support** collecting data from the clusters deployed using TiDB Ansible.
shichun-0415 marked this conversation as resolved.
Show resolved Hide resolved

## User scenarios

Expand All @@ -22,7 +22,7 @@ PingCAP Clinic is currently in the Technical Preview stage.

- [Perform a quick check on the cluster status locally](#perform-a-quick-check-on-the-cluster-status-locally)

Even if your cluster runs stably now, it is necessary to periodically check the cluster to avoid potential stability risks. You can check the potential health risks of a cluster using the local quick check feature provided by PingCAP Clinic. The PingCAP Clinic Technical Preview version provides a rationality check on cluster configuration items to discover unreasonable configurations and provide modification suggestions.
Even if your cluster runs stably now, it is necessary to periodically check the cluster to avoid potential stability risks. You can check the potential health risks of a cluster using the local quick check feature provided by PingCAP Clinic, which only checks configuration. For more detailed checks, it is recommended to upload the diagnostic data to the Clinic Server and use the Health Report feature to analyze metrics, logs, and configuration.
shichun-0415 marked this conversation as resolved.
Show resolved Hide resolved

## Prerequisites

Expand All @@ -32,16 +32,12 @@ Before using PingCAP Clinic, you need to install Diag (a component to collect da

- If you have installed TiUP on your control machine, run the following command to install Diag:

{{< copyable "shell-regular" >}}

```bash
tiup install diag
```

- If you have installed Diag, you can use the following command to upgrade Diag to the latest version:

{{< copyable "shell-regular" >}}

```bash
tiup update diag
```
Expand All @@ -55,25 +51,73 @@ Before using PingCAP Clinic, you need to install Diag (a component to collect da

When uploading collected data through Diag, you need a token for user authentication. If you already set a token Diag, you can reuse the token and skip this step.

To get a token, log in to [Clinic Server](https://clinic.pingcap.com.cn) and click the icon in the lower-right corner of the Cluster page. Next, select **Get Access Token For Diag Tool**, click **+** in the pop-up window. Make sure that you have copied and saved the displayed token information.
To get a token, follow the steps below:
shichun-0415 marked this conversation as resolved.
Show resolved Hide resolved

- Login in to the Clinic Server.
shichun-0415 marked this conversation as resolved.
Show resolved Hide resolved

<SimpleTab>
<div label="Clinic Server in Chinese mainland">

[Clinic Server in Chinese mainland](https://clinic.pingcap.com.cn): the collected data is stored in AWS China (Beijing).

</div>

<div label="Clinic Server in US">

[Clinic Server in US](https://clinic.pingcap.com): the collected data is stored in AWS US.

![Get the Token](/media/clinic-get-token.png)
</div>
</SimpleTab>

- Click the icon in the lower-right corner of the Cluster page and select **Get Access Token For Diag Tool**, click **+** in the pop-up window. Make sure that you have copied and saved the displayed token information.
shichun-0415 marked this conversation as resolved.
Show resolved Hide resolved

![Get the Token](/media/clinic-get-token.png)

> **Note:**
>
> - When accessing Clinic Server for the first time, before getting a token, you need to log in to [Clinic Server](https://clinic.pingcap.com.cn) using your AskTUG account and create an organization first.
> - For data security, TiDB only displays the token upon the token creation. If you have lost the token, delete the old token and create a new one.
> - A token is only used for uploading data.

Then, set the token in Diag. For example:
- Then, set the token in Diag. For example:

```bash
tiup diag config clinic.token ${token-value}
```

3. Set the `region` in Diag.

`region` determines the encryption certification used and the target service when uploading the data. For example:
shichun-0415 marked this conversation as resolved.
Show resolved Hide resolved

> **Note:**
>
> - Setting `region` is supported in Diag v0.9.0 and later versions.
> - For versions earlier than Diag v0.9.0, the data is uploaded to Clinic Server in Chinese mainland by default.
> - To set `region` in Diag earlier than v0.9.0, using `tiup update diag` command to upgrade Diag to the latest version and then set `region` in Diag.

{{< copyable "shell-regular" >}}
<SimpleTab>
<div label="Clinic Server in Chinese mainland">

For Clinic Server in Chinese mainland, set `region` to `CN` using the following command:

```bash
tiup diag config clinic.region CN
```

</div>

<div label="Clinic Server in US">

For Clinic Server in US, set `region` to `US` using the following command:

```bash
tiup diag config clinic.token ${token-value}
tiup diag config clinic.region US
```

3. (Optional) Enable log redaction.
</div>
</SimpleTab>

4. (Optional) Enable log redaction.

When TiDB provides detailed log information, it might print sensitive information (for example, user data) in the log. If you want to avoid leaking sensitive information in the local log and Clinic Server, you can enable log redaction in the TiDB side. For more information, see [log redaction](/log-redaction.md#log-redaction-in-tidb-side).

Expand All @@ -97,8 +141,6 @@ With Diag, you can collect data from the TiDB clusters and the DM clusters deplo

For example, to collect the diagnostic data from 4 hours ago to 2 hours ago based on the current time, run the following command:

{{< copyable "shell-regular" >}}

```bash
tiup diag collect ${cluster-name} -f="-4h" -t="-2h"
```
Expand All @@ -125,8 +167,6 @@ With Diag, you can collect data from the TiDB clusters and the DM clusters deplo

After you run the command, Diag does not start collecting data immediately. Instead, Diag provides the estimated data size and the target data storage path in the output for you to confirm whether to continue. For example:

{{< copyable "shell-regular" >}}

```bash
Estimated size of data to collect:
Host Size Target
Expand All @@ -146,8 +186,6 @@ With Diag, you can collect data from the TiDB clusters and the DM clusters deplo

After the collection is complete, Diag provides the folder path where the collected data is located. For example:

{{< copyable "shell-regular" >}}

```bash
Collected data are stored in /home/qiaodan/diag-fNTnz5MGhr6
```
Expand All @@ -158,8 +196,6 @@ With Diag, you can collect data from the TiDB clusters and the DM clusters deplo

For example, to collect the diagnostic data from 4 hours ago to 2 hours ago based on the current time, run the following command:

{{< copyable "shell-regular" >}}

```bash
tiup diag collectdm ${cluster-name} -f="-4h" -t="-2h"
```
Expand All @@ -174,8 +210,6 @@ With Diag, you can collect data from the TiDB clusters and the DM clusters deplo

After the collection is complete, Diag provides the folder path where the collected data is located. For example:

{{< copyable "shell-regular" >}}

```bash
Collected data are stored in /home/qiaodan/diag-fNTnz5MGhr6
```
Expand Down Expand Up @@ -204,7 +238,7 @@ Depending on the network connection of the cluster, you can choose one of the fo

> **Note:**
>
> If you did not set a token in Diag before uploading data, Diag reports the upload failure and reminds you to set a token. To set a token, see [the second step in Prerequisites](#prerequisites).
> If you did not set a token or `region` in Diag before uploading data, Diag reports the upload failure and reminds you to set. To set a token, see [the second step in Prerequisites](#prerequisites).
shichun-0415 marked this conversation as resolved.
Show resolved Hide resolved

#### Method 1. Upload directly

Expand All @@ -224,8 +258,6 @@ If the network where your cluster is located cannot access the internet, you nee

1. Pack the collected data obtained in [Step 2. Collect data](#step-2-collect-data) by running the following command:

{{< copyable "shell-regular" >}}

```bash
tiup diag package ${filepath}
```
Expand All @@ -241,16 +273,12 @@ If the network where your cluster is located cannot access the internet, you nee

2. From a machine with internet access, upload the compressed data package:

{{< copyable "shell-regular" >}}

```bash
tiup diag upload ${filepath}
```

The following is an example output:

{{< copyable "shell-regular" >}}

```bash
[root@Copy-of-VM-EE-CentOS76-v1 qiaodan]# tiup diag upload /home/qiaodan/diag-fNTnz5MGhr6
Starting component `diag`: /root/.tiup/components/diag/v0.7.0/diag upload /home/qiaodan/diag-fNTnz5MGhr6
Expand All @@ -267,8 +295,6 @@ You can have a quick check on the cluster status locally using Diag. Even if you

1. Collect configuration data:

{{< copyable "shell-regular" >}}

```bash
tiup diag collect ${cluster-name} --include="config"
```
Expand All @@ -277,8 +303,6 @@ You can have a quick check on the cluster status locally using Diag. Even if you

2. Diagnose configuration data:

{{< copyable "shell-regular" >}}

```bash
tiup diag check ${subdir-in-output-data}
```
Expand All @@ -289,8 +313,6 @@ You can have a quick check on the cluster status locally using Diag. Even if you

The diagnostic result is returned on the command line. For example:

{{< copyable "shell-regular" >}}

```bash
Starting component `diag`: /root/.tiup/components/diag/v0.7.0/diag check diag-fNTnz5MGhr6

Expand Down Expand Up @@ -345,8 +367,8 @@ You can have a quick check on the cluster status locally using Diag. Even if you

2. After uploading data, I cannot open the returned data access link. What should I do?

Try logging in to [Clinic Server](https://clinic.pingcap.com.cn) first. If you still cannot open the link, check whether you have permission to view the data. If not, contact the data owner for permission. After getting the permission, try logging in to Clinic Server and opening the link again.
Try logging in to Clinic Server first. If you still cannot open the link, check whether you have permission to view the data. If not, contact the data owner for permission. After getting the permission, try logging in to Clinic Server and opening the link again.
shichun-0415 marked this conversation as resolved.
Show resolved Hide resolved

3. How long will the uploaded data be kept on the Clinic Server?

After a technical support case is closed, PingCAP permanently deletes or anonymizes the corresponding data within 90 days.
The longest time is 180 days. You can delete the data you uploaded on the Clinic Server page at any time.
shichun-0415 marked this conversation as resolved.
Show resolved Hide resolved