From 6c6b92ad49d682153e3871990471d669cbb794bf Mon Sep 17 00:00:00 2001 From: djshow832 Date: Fri, 31 May 2024 10:59:52 +0800 Subject: [PATCH] tiproxy: add tiproxyctl commands and http api (#17340) --- TOC.md | 1 + tiproxy/tiproxy-api.md | 128 ++++++++++++++++++++++++++ tiproxy/tiproxy-command-line-flags.md | 66 +++++++++++-- 3 files changed, 187 insertions(+), 8 deletions(-) create mode 100644 tiproxy/tiproxy-api.md diff --git a/TOC.md b/TOC.md index a1e52bd498b1..d41bfdc673ab 100644 --- a/TOC.md +++ b/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) - 参考指南 diff --git a/tiproxy/tiproxy-api.md b/tiproxy/tiproxy-api.md new file mode 100644 index 000000000000..23c6173d0fb9 --- /dev/null +++ b/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/ +``` diff --git a/tiproxy/tiproxy-command-line-flags.md b/tiproxy/tiproxy-command-line-flags.md index 2d17d92e834a..6f1b8c3e7e57 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` 的参数。 +本节介绍 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} +``` \ No newline at end of file