tiproxy: add traffic replay doc

TOC.md

@@ -644,6 +644,7 @@
   - TiProxy
     - [概述](/tiproxy/tiproxy-overview.md)
     - [负载均衡策略](/tiproxy/tiproxy-load-balance.md)
+    - [流量回放](/tiproxy/tiproxy-traffic-replay.md)
     - [配置文件](/tiproxy/tiproxy-configuration.md)
     - [命令行参数](/tiproxy/tiproxy-command-line-flags.md)
     - [监控指标](/tiproxy/tiproxy-grafana.md)

tiproxy/tiproxy-command-line-flags.md

@@ -29,6 +29,27 @@ summary: 了解 TiProxy 的命令行参数。
 
 本节介绍 TiProxy 客户端程序 `tiproxyctl` 的语法、选项和命令。
 
+### 获取 TiProxy Control
+
+#### 通过 TiUP 安装
+
+在安装了 TiUP 之后，可以使用 `tiup install tiproxy` 命令来获取 TiProxy 和 TiProxy Control 的二进制程序。TiProxy 的路径可通过 `tiup --binary tiproxy` 查看，TiProxy Control 与 TiProxy 在同一个目录下。
+
+例如：
+
+```shell
+> tiup install tiproxy
+download https://tiup-mirrors.pingcap.com/tiproxy-v1.3.0-linux-amd64.tar.gz 22.51 MiB / 22.51 MiB 100.00% 13.99 MiB/s
+> ls `tiup --binary tiproxy`ctl
+/root/.tiup/components/tiproxy/v1.3.0/tiproxyctl
+```
+
+#### 从源代码编译安装
+
+编译环境要求：[Go](https://golang.org/) 1.21 或以上版本。
+
+编译步骤：在 [TiProxy 项目](https://github.com/pingcap/tiproxy)根目录，使用 `make` 命令进行编译，生成 tiproxyctl。
+
 > **注意：**
 >
 > TiProxy Control 主要用于诊断调试，不保证和 TiProxy 未来引入的新特性完全兼容。因此不推荐在应用程序开发或工具开发中利用 TiProxy Control 获取结果。
@@ -42,11 +63,23 @@ tiproxyctl [flags] [command]
 示例：
 
 ```
-tiproxyctl --curls 127.0.0.1:3080 config get
+tiproxyctl --host 127.0.0.1 --port 3080 config get
 ```
 
 ### 选项
 
+#### `--host`
+
++ 指定 TiProxy 服务器地址。
++ 类型：`string`
++ 默认值：`localhost`
+
+#### `--port`
+
++ 指定 TiProxy API 网关地址的端口号。
++ 类型：`int`
++ 默认值：`3080`
+
 #### `--log_encoder`
 
 + 指定 `tiproxyctl` 的日志格式。
@@ -64,13 +97,6 @@ tiproxyctl --curls 127.0.0.1:3080 config get
 + 默认值：`"warn"`
 + 可以指定以下日志级别之一：`debug`、`info`、`warn`、`error`、`panic`。
 
-#### `--curls`
-
-+ 指定服务器地址。可以添加多个监听地址。
-+ 类型：逗号分隔的 ip:port 列表
-+ 默认值：`localhost:3080`
-+ 服务器 API 网关地址。
-
 #### `-k, --insecure`
 
 + 指定是否在与服务器建立连接时跳过 TLS CA 验证。
@@ -120,4 +146,56 @@ level = 'warning'
 
 ```json
 {"config_checksum":3006078629}
-```
+```
+
+#### `traffic capture`
+
+`tiproxyctl traffic capture` 用于捕获流量。
+
+选项：
+
+- `--output`: 必须指定，指定流量文件存放的目录。
+- `--duration`: 必须指定，指定捕获的时长，可选单位为 `m` (分钟)、`h` (小时)、`d` (天)。例如 `--duration=1h` 指定捕获一小时的流量。
+
+例如，以下命令连接到 TiProxy 实例 `10.0.1.10:3080`，捕获一个小时的流量，并保存到 TiProxy 实例的 `/tmp/traffic` 目录下：
+
+```shell
+tiproxyctl traffic capture --host 10.0.1.10 --port 3080 --output="/tmp/traffic" --duration=1h
+```
+
+#### `traffic replay`
+
+`tiproxyctl traffic replay` 用于回放流量。
+
+选项：
+
+- `--username`: 必须指定，指定回放时使用的数据库用户名。
+- `--password`: 指定以上用户名的密码，默认为 `""`。
+- `--input`: 必须指定，指定流量文件存放的目录。
+- `--speed`: 回放速率的倍数，范围为 0.1 到 10，默认为 1，代表原速回放。
+
+例如，如下命令通过用户名 `u1` 和密码 `123456` 连接到 TiProxy 实例 `10.0.1.10:3080`，并从 TiProxy 实例的 `/tmp/traffic` 目录下读取流量文件，按 2 倍速率回放流量：
+
+```shell
+tiproxyctl traffic replay --host 10.0.1.10 --port 3080 --username="u1" --password="123456" --input="/tmp/traffic" --speed=2
+```
+
+#### `traffic cancel`
+
+`tiproxyctl traffic cancel` 用于取消当前的捕获任务或回放任务。
+
+#### `traffic show`
+
+`tiproxyctl traffic show` 用于显示历史的捕获和回放任务。
+
+输出中的 `status` 字段表示任务的状态，它有下列值：
+
+- `done`: 代表任务正常运行完成。
+- `canceled`: 代表任务被取消，`error` 字段描述了被取消的原因。
+- `running`: 代表任务正在运行，`progress` 字段描述了运行的进度。
+
+输出示例：
+
+```json
+[{"type":"capture","start_time":"2024-09-01T14:30:40.99096+08:00","end_time":"2024-09-01T16:30:40.99096+08:00","duration":"2h","output":"/tmp/triffic","progress":"100%","status":"done"},{"type":"capture","start_time":"2024-09-02T18:30:40.99096+08:00","end_time":"2024-09-02T19:00:40.99096+08:00","duration":"2h","output":"/tmp/triffic","progress":"25%","status":"canceled","error":"canceled manually"},{"type":"capture","start_time":"2024-09-03T13:31:40.99096+08:00","duration":"2h","output":"/tmp/triffic","progress":"45%","status":"running"}]
+```

tiproxy/tiproxy-traffic-replay.md

@@ -0,0 +1,132 @@
+---
+title: TiProxy 流量回放
+summary: 介绍 TiProxy 的流量回放的使用场景和使用步骤。
+---
+
+# TiProxy 流量回放
+
+> **警告：**
+>
+> TiProxy 流量回放目前为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tiproxy/issues) 反馈。
+
+从 v1.3.0 开始，TiProxy 支持捕获生产集群的流量，并将流量回放到测试集群。
+
+<img src="https://download.pingcap.com/images/docs-cn/tiproxy/tiproxy-traffic-replay.png" alt="TiProxy 流量回放" width="800" />
+
+## 使用场景
+
+流量回放适用于以下场景：
+
+- 升级 TiDB 版本之前，在新版本的测试集群上回放生产流量，验证新版本 TiDB 能成功执行所有 SQL 语句。
+- 在执行变更之前，在测试集群上用生产流量模拟，验证对集群的影响。例如变更配置项或系统变量、变更表结构、使用 TiDB 的新功能之前，先在测试集群验证效果。
+- 扩缩容 TiDB 之前，在新规模的测试集群上按对应速率回放流量，验证新规模集群的性能是否满足要求。例如，为了节省成本要将集群规模缩容到 1/2，则按 1/2 速率回放流量，验证缩容后 SQL 延迟是否满足要求。
+- 在相同规模的测试集群上多次回放流量，每次调大回放速率，测试该规模集群的吞吐量上限，以判断性能是否满足未来的业务增长。
+
+不适用于以下场景：
+
+- 从 MySQL 捕获流量后在 TiDB 上回放，验证 TiDB 与 MySQL 的 SQL 兼容性。TiProxy 只支持读取 TiProxy 生成的流量文件。
+- 验证新版本 TiDB 的 SQL 语句执行结果与旧版本相同。TiProxy 只验证 SQL 语句是否执行成功，不对比运行结果。
+
+## 使用步骤
+
+1. 创建测试集群，将生产集群的数据同步到测试集群，并在测试集群中运行 `ANALYZE` 更新统计信息。
+2. 使用 `tiproxyctl traffic capture` 命令连接到生产集群的 TiProxy 实例，开始捕获流量。TiProxy 会捕获所有连接上的流量，包括已创建的新创建的连接。
+
+    在 TiProxy 主备模式下，请确保连接到 TiProxy 主实例。如果集群使用了虚拟 IP，建议连接到虚拟 IP 地址。
+
+    例如，以下命令连接到 TiProxy 实例 `10.0.1.10:3080`，捕获一个小时的流量，并将流量保存到 TiProxy 实例的 `/tmp/traffic` 目录下：
+
+    ```shell
+    tiproxyctl traffic capture --host 10.0.1.10 --port 3080 --output="/tmp/traffic" --duration=1h
+    ```
+
+    流量文件会自动转轮和压缩。`/tmp/traffic` 目录下的文件样例：
+
+    ```shell
+    $ ls /tmp/traffic
+    meta    traffic-2024-08-29T17-37-12.477.log.gz  traffic-2024-08-29T17-43-11.166.log.gz traffic.log
+    ```
+
+    更多详细信息请参考 [`tiproxyctl traffic capture`](/tiproxy/tiproxy-command-line-flags.md#traffic-capture) 的使用文档。
+
+3. 将流量文件目录复制到测试集群的 TiProxy 实例上。
+4. 使用 `tiproxyctl traffic replay` 连接到测试集群的 TiProxy 实例，开始回放流量。
+
+    默认配置下，SQL 语句的执行速率与生产集群相同，数据库连接也与生产集群一一对应，以模拟生产集群的负载，并保证事务的执行顺序一致。
+
+    例如，如下命令通过用户名 `u1` 和密码 `123456` 连接到 TiProxy 实例 `10.0.1.10:3080`，并从 TiProxy 实例的 `/tmp/traffic` 目录下读取流量文件，并回放流量：
+
+    ```shell
+    tiproxyctl traffic replay --host 10.0.1.10 --port 3080 --username="u1" --password="123456" --input="/tmp/traffic"
+    ```
+
+    由于所有流量在用户 `u1` 下运行，请确保 `u1` 能访问所有数据库和表。如果没有这样的用户，则需要创建一个。
+
+    更多详细信息请参考 [`tiproxyctl traffic replay`](/tiproxy/tiproxy-command-line-flags.md#traffic-replay) 的使用文档。
+
+5. 回放完成之后，报告存储在测试集群的 `tiproxy_traffic_report` 数据库下。该数据库下有两个表，`fail` 和 `other_errors`。
+
+    表 `fail` 存储运行失败的 SQL 语句。它的字段如下：
+
+    - `cmd_type`: 运行错误的命令类型，常见的有 `Query`(执行普通语句)、`Prepare`(预处理语句)、`Execute`(执行预处理语句)。
+    - `digest`: 执行失败的 SQL 语句的指纹。
+    - `sample_stmt`: 该 SQL 语句首次执行失败时的 SQL 文本。
+    - `sample_err_msg`: 以上 SQL 语句执行失败的报错信息。
+    - `sample_conn_id`: 以上 SQL 语句在流量文件中记录的连接 ID，可用于在流量文件中查看 SQL 语句的执行上下文。
+    - `sample_capture_time`: 以上 SQL 语句在流量文件中记录的执行时间，可用于在流量文件中查看 SQL 语句的执行上下文。
+    - `sample_replay_time`: 以上 SQL 语句在回放时执行失败的时间，可用于在 TiDB 日志文件中查看错误信息。
+    - `count`: 该 SQL 语句执行失败的次数。
+
+    表 `other_errors` 存储其他未预期错误，例如网络错误、连接数据库错误。它的字段如下：
+
+    - `err_type`: 该错误的类型，是一个简短的错误信息，例如 `i/o timeout`。
+    - `sample_err_msg`: 该错误首次出现时的完整错误信息。
+    - `sample_replay_time`: 该错误在回放时执行失败的时间，可用于在 TiDB 日志文件中查看错误信息。
+    - `count`: 该错误出现的次数。
+
+    > **注意：**
+    >
+    > `tiproxy_traffic_report` 中的表结构在后续版本中可能会改变，因此不推荐在应用程序开发或工具开发中读取 `tiproxy_traffic_report` 中的数据。
+
+## 测试吞吐量
+
+如果需要测试集群的吞吐量，可以加上 `--speed` 选项调整回放的速率。
+
+例如，加上 `--speed=2` 后，SQL 语句的执行间隔缩短，以 2 倍速率执行，总的回放时间缩短一半：
+
+```shell
+tiproxyctl traffic replay --host 10.0.1.10 --port 3080 --username="u1" --password="123456" --input="/tmp/traffic" --speed=2
+```
+
+调大回放速率只缩短会话的空闲时间，不增加连接数。因此当会话的空闲时间本身就较短时，调大倍速无法加大吞吐量。这时需要部署更多 TiProxy 实例，让它们同时回放相同的流量文件，通过增加并发度来加大吞吐量。
+
+## 任务查看与管理
+
+在捕获和回放过程中，如果遇到未知错误会自动停止任务。通过 `tiproxyctl traffic show` 命令可查看当前的任务进度或上次任务的错误信息：
+
+```shell
+tiproxyctl traffic show --host 10.0.1.10 --port 3080
+```
+
+例如，如下输出代表捕获任务正在运行：
+
+```json
+[{"type":"capture","start_time":"2024-09-03T09:10:58.220644+08:00","duration":"2h","progress":"45%","status":"running"}]
+```
+
+更多详细信息请参考 [`tiproxyctl traffic show`](/tiproxy/tiproxy-command-line-flags.md#traffic-show) 的使用文档。
+
+如果需要取消当前的捕获或回放任务，可使用 `tiproxyctl traffic cancel` 命令：
+
+```shell
+tiproxyctl traffic cancel --host 10.0.1.10 --port 3080
+```
+
+更多详细信息请参考 [`tiproxyctl traffic cancel`](/tiproxy/tiproxy-command-line-flags.md#traffic-cancel) 的使用文档。
+
+## 使用限制
+
+- TiProxy 仅支持回放 TiProxy 捕获的流量文件，不支持其他文件格式，因此生产集群使用了 TiProxy 之后才能捕获和回放流量。
+- TiProxy 不支持过滤 SQL 类型，DML 或 DDL 语句也会回放，因此重新回放前需要恢复集群数据到回放之前的状态。
+- 由于 TiProxy 使用同一个用户名回放流量，因此不能测试[资源管控](/tidb-resource-control.md)和[权限管理](/privilege-management.md)。
+- 不支持回放 [`LOAD DATA`](/sql-statements/sql-statement-load-data.md) 语句。