From 98c01312063b3db098ebed45087c70d0a563df22 Mon Sep 17 00:00:00 2001 From: djshow832 Date: Tue, 14 May 2024 16:27:58 +0800 Subject: [PATCH 1/5] add tiproxyctl commands and http api --- TOC.md | 1 + tiproxy/tiproxy-api.md | 64 +++++++++++++++++++++++++++ tiproxy/tiproxy-command-line-flags.md | 64 ++++++++++++++++++++++++--- 3 files changed, 122 insertions(+), 7 deletions(-) create mode 100644 tiproxy/tiproxy-api.md diff --git a/TOC.md b/TOC.md index b3a6904df0b2..c66f81ef290e 100644 --- a/TOC.md +++ b/TOC.md @@ -635,6 +635,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) - 参考指南 diff --git a/tiproxy/tiproxy-api.md b/tiproxy/tiproxy-api.md new file mode 100644 index 000000000000..3b3767dec0aa --- /dev/null +++ b/tiproxy/tiproxy-api.md @@ -0,0 +1,64 @@ +--- +title: TiProxy API +summary: 了解 TiProxy 的 API。 +--- + +# TiProxy API + +本文介绍了 TiProxy 的 API。 + +> **注意：** +> +> TiProxy API 主要用于诊断调试，不保证和 TiProxy 未来引入的新特性完全兼容。因此不推荐客户在应用程序开发或工具开发中利用 TiProxy API 获取结果。 + +## 使用方法 + +TiProxy API 地址：`http://${host}:${port}` + +其中 `host` 和 `port` 由 TiProxy 配置中的 [api.addr](/tiproxy/tiproxy-configuration.md#addr-1) 指定。 + +例如： + +```bash +curl http://127.0.0.1:3080/api/admin/config/ +``` + +## API + +### 配置 + +`/api/admin/config/` 用于设置或获取 TiProxy 配置。 + +当使用 `GET` 方式访问 `/api/admin/config/` 时，API 返回当前配置。可通过 `format` 指定格式，支持 `json` 和 `toml` 格式，默认为 `toml` 格式。 + +例如获取 `json` 格式的配置： + +```bash +curl "http://127.0.0.1:3080/api/admin/config/?format=json" +``` + +当使用 `PUT` 方式访问 `/api/admin/config/` 时，给 TiProxy 设置 `toml` 格式的配置。其他未指定的配置项将不会改变，因此你只需指定需要更改的配置项。 + +例如，以下命令将 `log.level` 设置为 `warning`，其他配置项的值不会改变： + +```bash +$ cat test.toml +[log] +level='warning' +$ curl -X PUT --data-binary @test.toml http://127.0.0.1:3080/api/admin/config/ +``` + +### 健康 + +`/api/debug/health` 用于获取 TiProxy 的健康状况以及配置的 checksum。当 TiProxy 正常运行时，返回配置的 checksum；当 TiProxy 正在关闭时，返回错误。 + +例如： + +```bash +$ curl http://127.0.0.1:3080/api/debug/health +{"config_checksum":3006078629} +``` + +### 监控 + +`/metrics` 用于获取 TiProxy 的监控数据。 \ No newline at end of file diff --git a/tiproxy/tiproxy-command-line-flags.md b/tiproxy/tiproxy-command-line-flags.md index 2d17d92e834a..9291b1a7828f 100644 --- a/tiproxy/tiproxy-command-line-flags.md +++ b/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` 的参数。 -### `--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 + +`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 + +用于获取当前 TiProxy 的配置，输出格式为 `toml`。 + +#### health + +用于获取 TiProxy 的健康状况以及配置的 checksum。当 TiProxy 正常运行时，返回配置的 checksum；当 TiProxy 正在关闭时，返回错误。 + +输出示例为： + +```json +{"config_checksum":3006078629} +``` \ No newline at end of file From a6bdc848507e12889c5f7c5175cf5c100601fa21 Mon Sep 17 00:00:00 2001 From: Aolin Date: Tue, 28 May 2024 18:59:07 +0800 Subject: [PATCH 2/5] TiProxy API: revise wording and format --- tiproxy/tiproxy-api.md | 116 ++++++++++++++++++++------ tiproxy/tiproxy-command-line-flags.md | 16 ++-- 2 files changed, 98 insertions(+), 34 deletions(-) diff --git a/tiproxy/tiproxy-api.md b/tiproxy/tiproxy-api.md index 3b3767dec0aa..bd9235efcc72 100644 --- a/tiproxy/tiproxy-api.md +++ b/tiproxy/tiproxy-api.md @@ -1,64 +1,128 @@ --- title: TiProxy API -summary: 了解 TiProxy 的 API。 +summary: 了解如何使用 TiProxy API 获取 TiProxy 的配置、健康状况和监控数据等信息。 --- # TiProxy API -本文介绍了 TiProxy 的 API。 +[TiProxy](/tiproxy/tiproxy-overview.md) 提供 API 接口，用于获取其配置、健康状况以及监控数据等信息。 > **注意：** > -> TiProxy API 主要用于诊断调试，不保证和 TiProxy 未来引入的新特性完全兼容。因此不推荐客户在应用程序开发或工具开发中利用 TiProxy API 获取结果。 +> TiProxy API 主要用于诊断调试，不保证与 TiProxy 未来引入的新特性完全兼容。因此不推荐客户在应用程序开发或工具开发中利用 TiProxy API 获取结果。 -## 使用方法 - -TiProxy API 地址：`http://${host}:${port}` - -其中 `host` 和 `port` 由 TiProxy 配置中的 [api.addr](/tiproxy/tiproxy-configuration.md#addr-1) 指定。 - -例如： +TiProxy API 的地址为 `http://${host}:${port}`，其中 `host` 和 `port` 由 TiProxy 配置项 [`api.addr`](/tiproxy/tiproxy-configuration.md#addr-1) 指定。例如： ```bash curl http://127.0.0.1:3080/api/admin/config/ ``` -## API +## 获取 TiProxy 的配置 + +### 请求 URI + +`GET /api/admin/config/` -### 配置 +### 参数说明 -`/api/admin/config/` 用于设置或获取 TiProxy 配置。 +查询参数： -当使用 `GET` 方式访问 `/api/admin/config/` 时，API 返回当前配置。可通过 `format` 指定格式，支持 `json` 和 `toml` 格式，默认为 `toml` 格式。 +- `format`：（可选）指定返回配置的格式，可选值为 `json` 和 `toml`，默认值为 `toml`。 -例如获取 `json` 格式的配置： +### 使用样例 + +以下示例获取 JSON 格式的 TiProxy 配置： ```bash curl "http://127.0.0.1:3080/api/admin/config/?format=json" ``` -当使用 `PUT` 方式访问 `/api/admin/config/` 时，给 TiProxy 设置 `toml` 格式的配置。其他未指定的配置项将不会改变，因此你只需指定需要更改的配置项。 +## 设置 TiProxy 的配置 -例如，以下命令将 `log.level` 设置为 `warning`，其他配置项的值不会改变： +使用 TOML 格式修改 TiProxy 的配置。未指定的配置项将保持不变，因此只需指定需要更改的配置项。 -```bash -$ cat test.toml +### 请求 URI + +`PUT /api/admin/config/` + +### 请求体 + +TOML 格式的 TiProxy 的配置，例如： + +```toml [log] level='warning' -$ curl -X PUT --data-binary @test.toml http://127.0.0.1:3080/api/admin/config/ ``` -### 健康 +### 使用样例 + +以下示例将 `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` 的值： -`/api/debug/health` 用于获取 TiProxy 的健康状况以及配置的 checksum。当 TiProxy 正常运行时，返回配置的 checksum；当 TiProxy 正在关闭时，返回错误。 + ```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 -$ curl http://127.0.0.1:3080/api/debug/health {"config_checksum":3006078629} ``` -### 监控 +## 获取 TiProxy 的监控数据 + +### 请求 URI -`/metrics` 用于获取 TiProxy 的监控数据。 \ No newline at end of file +`GET /metrics/` + +### 使用样例 + +```bash +curl http://127.0.0.1:3080/metrics/ +``` diff --git a/tiproxy/tiproxy-command-line-flags.md b/tiproxy/tiproxy-command-line-flags.md index 9291b1a7828f..6df3003cabea 100644 --- a/tiproxy/tiproxy-command-line-flags.md +++ b/tiproxy/tiproxy-command-line-flags.md @@ -85,11 +85,11 @@ tiproxyctl --curls 127.0.0.1:3080 config get ### 命令 -#### config set +#### `config set` -`config set` 从标准输入中读取 `toml` 格式的配置，并把这些配置项设置到 TiProxy。其他未指定的配置项将不会改变，因此你只需指定需要更改的配置项。 +`config set` 从标准输入读取 TOML 格式的配置，并将这些配置项设置到 TiProxy。其他未指定的配置项将保持不变，因此只需指定需要更改的配置项。 -例如，以下命令将 `log.level` 设置为 `warning`，其他配置项的值不会改变： +以下命令将 `log.level` 设置为 `"warning"`，其他配置项的值保持不变： ```bash $ cat test.toml @@ -101,15 +101,15 @@ $ tiproxyctl config get | grep level level = 'warning' ``` -#### config get +#### `config get` -用于获取当前 TiProxy 的配置，输出格式为 `toml`。 +用于获取当前 TiProxy 的配置，输出格式为 TOML。 -#### health +#### `health` -用于获取 TiProxy 的健康状况以及配置的 checksum。当 TiProxy 正常运行时，返回配置的 checksum；当 TiProxy 正在关闭时，返回错误。 +用于获取 TiProxy 的健康状况以及配置的校验和 (checksum)。当 TiProxy 正常运行时，返回配置的 checksum。当 TiProxy 正在关闭时，返回错误。 -输出示例为： +输出示例： ```json {"config_checksum":3006078629} From 6b7a1b65b84a9defb5ff28fdaa530e0fa6c868f0 Mon Sep 17 00:00:00 2001 From: djshow832 Date: Wed, 29 May 2024 12:28:12 +0800 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Aolin --- tiproxy/tiproxy-command-line-flags.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tiproxy/tiproxy-command-line-flags.md b/tiproxy/tiproxy-command-line-flags.md index 6df3003cabea..9c306b810245 100644 --- a/tiproxy/tiproxy-command-line-flags.md +++ b/tiproxy/tiproxy-command-line-flags.md @@ -20,7 +20,7 @@ summary: 了解 TiProxy 的命令行参数。 ## TiProxy Control -本节介绍 TiProxy 客户端程序 `tiproxyctl` 的参数。 +本节介绍 TiProxy 客户端程序 `tiproxyctl` 的语法、选项和命令。 > **注意：** > @@ -87,7 +87,7 @@ tiproxyctl --curls 127.0.0.1:3080 config get #### `config set` -`config set` 从标准输入读取 TOML 格式的配置，并将这些配置项设置到 TiProxy。其他未指定的配置项将保持不变，因此只需指定需要更改的配置项。 +`tiproxyctl config set` 从标准输入读取 TOML 格式的配置，并将这些配置项设置到 TiProxy。其他未指定的配置项将保持不变，因此只需指定需要更改的配置项。 以下命令将 `log.level` 设置为 `"warning"`，其他配置项的值保持不变： @@ -103,11 +103,11 @@ level = 'warning' #### `config get` -用于获取当前 TiProxy 的配置，输出格式为 TOML。 +`tiproxyctl config get` 用于获取当前 TiProxy 的配置，输出格式为 TOML。 #### `health` -用于获取 TiProxy 的健康状况以及配置的校验和 (checksum)。当 TiProxy 正常运行时，返回配置的 checksum。当 TiProxy 正在关闭时，返回错误。 +`tiproxyctl health` 用于获取 TiProxy 的健康状况以及配置的校验和 (checksum)。当 TiProxy 正常运行时，返回配置的 checksum。当 TiProxy 正在关闭时，返回错误。 输出示例： From 4f59452594039e249638eefd714edf1f0cbba2b0 Mon Sep 17 00:00:00 2001 From: djshow832 Date: Thu, 30 May 2024 09:29:36 +0800 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Grace Cai --- tiproxy/tiproxy-api.md | 4 ++-- tiproxy/tiproxy-command-line-flags.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tiproxy/tiproxy-api.md b/tiproxy/tiproxy-api.md index bd9235efcc72..8b3791e20f35 100644 --- a/tiproxy/tiproxy-api.md +++ b/tiproxy/tiproxy-api.md @@ -9,7 +9,7 @@ summary: 了解如何使用 TiProxy API 获取 TiProxy 的配置、健康状况 > **注意：** > -> TiProxy API 主要用于诊断调试，不保证与 TiProxy 未来引入的新特性完全兼容。因此不推荐客户在应用程序开发或工具开发中利用 TiProxy API 获取结果。 +> TiProxy API 主要用于诊断调试，不保证与 TiProxy 未来引入的新特性完全兼容。因此不推荐在应用程序开发或工具开发中利用 TiProxy API 获取结果。 TiProxy API 的地址为 `http://${host}:${port}`，其中 `host` 和 `port` 由 TiProxy 配置项 [`api.addr`](/tiproxy/tiproxy-configuration.md#addr-1) 指定。例如： @@ -56,7 +56,7 @@ level='warning' ### 使用样例 -以下示例将 `log.level` 设置为 `"warning"`，其他配置项的值保持不变。 +以下示例将 `log.level` 设置为 `'warning'`，其他配置项的值保持不变。 1. 查看当前 TiProxy 的配置： diff --git a/tiproxy/tiproxy-command-line-flags.md b/tiproxy/tiproxy-command-line-flags.md index 9c306b810245..739909219c89 100644 --- a/tiproxy/tiproxy-command-line-flags.md +++ b/tiproxy/tiproxy-command-line-flags.md @@ -24,7 +24,7 @@ summary: 了解 TiProxy 的命令行参数。 > **注意：** > -> TiProxy Control 主要用于诊断调试，不保证和 TiProxy 未来引入的新特性完全兼容。因此不推荐客户在应用程序开发或工具开发中利用 TiProxy Control 获取结果。 +> TiProxy Control 主要用于诊断调试，不保证和 TiProxy 未来引入的新特性完全兼容。因此不推荐在应用程序开发或工具开发中利用 TiProxy Control 获取结果。 ### 语法 @@ -89,7 +89,7 @@ tiproxyctl --curls 127.0.0.1:3080 config get `tiproxyctl config set` 从标准输入读取 TOML 格式的配置，并将这些配置项设置到 TiProxy。其他未指定的配置项将保持不变，因此只需指定需要更改的配置项。 -以下命令将 `log.level` 设置为 `"warning"`，其他配置项的值保持不变： +以下命令将 `log.level` 设置为 `'warning'`，其他配置项的值保持不变： ```bash $ cat test.toml From 84d4e7a9ce11c87fb023028edf32de66bc55cd08 Mon Sep 17 00:00:00 2001 From: djshow832 Date: Thu, 30 May 2024 20:19:36 +0800 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Grace Cai --- tiproxy/tiproxy-api.md | 6 +++--- tiproxy/tiproxy-command-line-flags.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/tiproxy/tiproxy-api.md b/tiproxy/tiproxy-api.md index 8b3791e20f35..23c6173d0fb9 100644 --- a/tiproxy/tiproxy-api.md +++ b/tiproxy/tiproxy-api.md @@ -11,7 +11,7 @@ summary: 了解如何使用 TiProxy API 获取 TiProxy 的配置、健康状况 > > TiProxy API 主要用于诊断调试，不保证与 TiProxy 未来引入的新特性完全兼容。因此不推荐在应用程序开发或工具开发中利用 TiProxy API 获取结果。 -TiProxy API 的地址为 `http://${host}:${port}`，其中 `host` 和 `port` 由 TiProxy 配置项 [`api.addr`](/tiproxy/tiproxy-configuration.md#addr-1) 指定。例如： +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/ @@ -39,7 +39,7 @@ curl "http://127.0.0.1:3080/api/admin/config/?format=json" ## 设置 TiProxy 的配置 -使用 TOML 格式修改 TiProxy 的配置。未指定的配置项将保持不变，因此只需指定需要更改的配置项。 +目前，仅支持使用 TOML 格式修改 TiProxy 的配置。未指定的配置项将保持不变，因此只需指定需要更改的配置项。 ### 请求 URI @@ -97,7 +97,7 @@ level='warning' ## 获取 TiProxy 的健康状况 -用于获取 TiProxy 的健康状况以及配置的校验和 (checksum)。当 TiProxy 正常运行时，返回配置的 checksum。当 TiProxy 正在关闭时，返回错误。 +用于获取 TiProxy 的健康状况以及配置的校验和 (checksum)。当 TiProxy 正常运行时，返回配置的 checksum。当 TiProxy 处于关闭状态或者正在关闭时，返回错误。 ### 请求 URI diff --git a/tiproxy/tiproxy-command-line-flags.md b/tiproxy/tiproxy-command-line-flags.md index 739909219c89..6f1b8c3e7e57 100644 --- a/tiproxy/tiproxy-command-line-flags.md +++ b/tiproxy/tiproxy-command-line-flags.md @@ -87,7 +87,7 @@ tiproxyctl --curls 127.0.0.1:3080 config get #### `config set` -`tiproxyctl config set` 从标准输入读取 TOML 格式的配置，并将这些配置项设置到 TiProxy。其他未指定的配置项将保持不变，因此只需指定需要更改的配置项。 +`tiproxyctl config set` 从标准输入读取 TOML 格式的配置文件，并将这些配置项设置到 TiProxy。其他未指定的配置项将保持不变，因此只需指定需要更改的配置项。 以下命令将 `log.level` 设置为 `'warning'`，其他配置项的值保持不变： @@ -107,7 +107,7 @@ level = 'warning' #### `health` -`tiproxyctl health` 用于获取 TiProxy 的健康状况以及配置的校验和 (checksum)。当 TiProxy 正常运行时，返回配置的 checksum。当 TiProxy 正在关闭时，返回错误。 +`tiproxyctl health` 用于获取 TiProxy 的健康状况以及配置的校验和 (checksum)。当 TiProxy 正常运行时，返回配置的 checksum。当 TiProxy 处于关闭状态或者正在关闭时，返回错误。 输出示例：