tiproxy: add tiproxyctl commands and http api (pingcap#17340)

TOC.md

@@ -637,6 +637,7 @@
     - [配置文件](/tiproxy/tiproxy-configuration.md)
     - [命令行参数](/tiproxy/tiproxy-command-line-flags.md)
     - [监控指标](/tiproxy/tiproxy-grafana.md)
+    - [API](/tiproxy/tiproxy-api.md)
     - [故障诊断](/tiproxy/troubleshoot-tiproxy.md)
     - [性能测试报告](/tiproxy/tiproxy-performance-test.md)
 - 参考指南

tiproxy/tiproxy-api.md

@@ -0,0 +1,128 @@
+---
+title: TiProxy API
+summary: 了解如何使用 TiProxy API 获取 TiProxy 的配置、健康状况和监控数据等信息。
+---
+
+# TiProxy API
+
+[TiProxy](/tiproxy/tiproxy-overview.md) 提供 API 接口，用于获取其配置、健康状况以及监控数据等信息。
+
+> **注意：**
+>
+> TiProxy API 主要用于诊断调试，不保证与 TiProxy 未来引入的新特性完全兼容。因此不推荐在应用程序开发或工具开发中利用 TiProxy API 获取结果。
+
+TiProxy API 的地址为 `http://${host}:${port}${path}`，其中 `${host}:${port}` 为 TiProxy 配置项 [`api.addr`](/tiproxy/tiproxy-configuration.md#addr-1) 的值，`${path}` 为你要访问的具体 API 的路径。例如：
+
+```bash
+curl http://127.0.0.1:3080/api/admin/config/
+```
+
+## 获取 TiProxy 的配置
+
+### 请求 URI
+
+`GET /api/admin/config/`
+
+### 参数说明
+
+查询参数：
+
+- `format`：（可选）指定返回配置的格式，可选值为 `json` 和 `toml`，默认值为 `toml`。
+
+### 使用样例
+
+以下示例获取 JSON 格式的 TiProxy 配置：
+
+```bash
+curl "http://127.0.0.1:3080/api/admin/config/?format=json"
+```
+
+## 设置 TiProxy 的配置
+
+目前，仅支持使用 TOML 格式修改 TiProxy 的配置。未指定的配置项将保持不变，因此只需指定需要更改的配置项。
+
+### 请求 URI
+
+`PUT /api/admin/config/`
+
+### 请求体
+
+TOML 格式的 TiProxy 的配置，例如：
+
+```toml
+[log]
+level='warning'
+```
+
+### 使用样例
+
+以下示例将 `log.level` 设置为 `'warning'`，其他配置项的值保持不变。
+
+1. 查看当前 TiProxy 的配置：
+
+    ```bash
+    curl http://127.0.0.1:3080/api/admin/config/
+    ```
+
+    输出结果如下：
+
+    ```toml
+    [log]
+    encoder = 'tidb'
+    level = 'info'
+    ```
+
+2. 在 `test.toml` 文件中指定 `log.level` 的值，并发送 `PUT /api/admin/config/` 请求更新 `log.level` 的值：
+
+    ```shell
+    $ cat test.toml
+    [log]
+    level='warning'
+    $ curl -X PUT --data-binary @test.toml http://127.0.0.1:3080/api/admin/config/
+    ```
+
+3. 查看修改后的 TiProxy 配置：
+
+    ```bash
+    curl http://127.0.0.1:3080/api/admin/config/
+    ```
+
+    输出结果如下：
+
+    ```toml
+    [log]
+    encoder = 'tidb'
+    level = 'warning'
+    ```
+
+## 获取 TiProxy 的健康状况
+
+用于获取 TiProxy 的健康状况以及配置的校验和 (checksum)。当 TiProxy 正常运行时，返回配置的 checksum。当 TiProxy 处于关闭状态或者正在关闭时，返回错误。
+
+### 请求 URI
+
+`GET /api/debug/health`
+
+### 使用样例
+
+```bash
+curl http://127.0.0.1:3080/api/debug/health
+```
+
+输出结果示例：
+
+```bash
+{"config_checksum":3006078629}
+```
+
+## 获取 TiProxy 的监控数据
+
+### 请求 URI
+
+`GET /metrics/`
+
+### 使用样例
+
+```bash
+curl http://127.0.0.1:3080/metrics/
+```

tiproxy/tiproxy-command-line-flags.md

@@ -18,11 +18,29 @@ summary: 了解 TiProxy 的命令行参数。
 + 默认值：`""`
 + 必须指定配置文件。有关详细配置项，请参见[配置 TiProxy](/tiproxy/tiproxy-configuration.md)。注意，修改配置文件时 TiProxy 会自动重新加载配置，因此不要直接修改配置文件，建议通过 [`tiup cluster edit-config`](/tiup/tiup-component-cluster-edit-config.md) 或 [`kubectl edit tc`](https://docs.pingcap.com/zh/tidb-in-kubernetes/dev/modify-tidb-configuration) 修改配置。
 
-## TiProxy control
+## TiProxy Control
 
-本节介绍 TiProxy 客户端程序 `tiproxyctl` 的参数。
+本节介绍 TiProxy 客户端程序 `tiproxyctl` 的语法、选项和命令。
 
-### `--log_encoder`
+> **注意：**
+>
+> TiProxy Control 主要用于诊断调试，不保证和 TiProxy 未来引入的新特性完全兼容。因此不推荐在应用程序开发或工具开发中利用 TiProxy Control 获取结果。
+
+### 语法
+
+```
+tiproxyctl [flags] [command]
+```
+
+示例：
+
+```
+tiproxyctl --curls 127.0.0.1:3080 config get
+```
+
+### 选项
+
+#### `--log_encoder`
 
 + 指定 `tiproxyctl` 的日志格式。
 + 类型：`string`
@@ -32,35 +50,67 @@ summary: 了解 TiProxy 的命令行参数。
     - `console`：更易读的格式
     - `json`：结构化日志格式
 
-### `--log_level`
+#### `--log_level`
 
 + 指定 `tiproxyctl` 的日志级别。
 + 类型：`string`
 + 默认值：`"warn"`
 + 可以指定以下日志级别之一：`debug`、`info`、`warn`、`error`、`panic`。
 
-### `--curls`
+#### `--curls`
 
 + 指定服务器地址。可以添加多个监听地址。
 + 类型：逗号分隔的 ip:port 列表
 + 默认值：`localhost:3080`
 + 服务器 API 网关地址。
 
-### `-k, --insecure`
+#### `-k, --insecure`
 
 + 指定是否在与服务器建立连接时跳过 TLS CA 验证。
 + 类型：`boolean`
 + 默认值：`false`
 + 用于测试。
 
-### `--ca`
+#### `--ca`
 
 + 指定在与服务器建立连接时使用的 CA。
 + 类型：`string`
 + 默认值：`""`
 
-### `--cert`
+#### `--cert`
 
 + 指定在与服务器建立连接时使用的证书。
 + 类型：`string`
 + 默认值：`""`
+
+### 命令
+
+#### `config set`
+
+`tiproxyctl config set` 从标准输入读取 TOML 格式的配置文件，并将这些配置项设置到 TiProxy。其他未指定的配置项将保持不变，因此只需指定需要更改的配置项。
+
+以下命令将 `log.level` 设置为 `'warning'`，其他配置项的值保持不变：
+
+```bash
+$ cat test.toml
+[log]
+level='warning'
+$ cat test.toml | tiproxyctl config set
+""
+$ tiproxyctl config get | grep level
+level = 'warning'
+```
+
+#### `config get`
+
+`tiproxyctl config get` 用于获取当前 TiProxy 的配置，输出格式为 TOML。
+
+#### `health`
+
+`tiproxyctl health` 用于获取 TiProxy 的健康状况以及配置的校验和 (checksum)。当 TiProxy 正常运行时，返回配置的 checksum。当 TiProxy 处于关闭状态或者正在关闭时，返回错误。
+
+输出示例：
+
+```json
+{"config_checksum":3006078629}
+```