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

[WEB] Revise balancer documentation #1389

Merged
merged 2 commits into from
Jan 3, 2023
Merged

[WEB] Revise balancer documentation #1389

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
78b86f8
Revise balancer introduction
garyparrot Jan 2, 2023
5a8d80b
Replace 負載平衡計劃 by 負載優化計劃
garyparrot Jan 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 13 additions & 2 deletions docs/balancer/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,15 @@
# Astraea Balancer

* [實驗報告#1](experiment_1.md)
* [實驗報告#2](experiment_2.md)
Kafka 的負載(Partition)本身依照較為簡單的邏輯分配在叢集內的各個節點，這個簡單的邏輯沒有顧及到許多維護上應該注意的資源分配議題
(節點流量, 儲存空間消耗, 時間週期行為...)，對此許多 Kafka 叢集會遭遇到一些日常維護的問題，比如訊息傳遞延遲在尖峰時變高、
傳輸吞吐量遭遇瓶頸、Partition 因儲存空間用盡而下線、或是叢集資源利用率不高。

Astraea Balancer 是一個 Kafka 節點端的負載優化框架，其透過使用者自定的優化目標來重新分配 Kafka 叢集內的負載(Partition)位置，
來確保叢集的資源使用表現符合特定的預期或盡可能遠離某些風險。

* Astraea Balancer 使用文件
* [WebService](../web_server/web_api_balancer_chinese.md)
* [GUI](../gui/balancer/README.md)
* Astraea Balancer 實驗報告
* [實驗報告#1](experiment_1.md)
* [實驗報告#2](experiment_2.md)
74 changes: 37 additions & 37 deletions docs/web_server/web_api_balancer_chinese.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
/balancer
===

- [排程搜尋新的負載平衡計劃](#排程搜尋新的負載平衡計劃)
- [執行負載平衡計劃](#執行負載平衡計劃)
- [查詢負載平衡計劃的狀態](#查詢負載平衡計劃的狀態)
- [排程搜尋新的負載優化計劃](#排程搜尋新的負載優化計劃)
- [執行負載優化計劃](#執行負載優化計劃)
- [查詢負載優化計劃的狀態](#查詢負載優化計劃的狀態)

## 排程搜尋新的負載平衡計劃
## 排程搜尋新的負載優化計劃
```shell
POST /balancer
```
Expand All @@ -16,7 +16,7 @@ POST /balancer
|-------------------|------------------------------------------------------------|-------------------------------------------------------|
| topics | (選填) 只嘗試搬移指定的 topics | 無，除了內部 topics 以外的都作為候選對象 |
| timeout | (選填) 指定產生時間 | 3s |
| balancer | (選填) 欲使用的負載平衡計劃搜尋演算法 | org.astraea.common.balancer.algorithms.GreedyBalancer |
| balancer | (選填) 欲使用的負載優化計劃搜尋演算法 | org.astraea.common.balancer.algorithms.GreedyBalancer |
| balancerConfig | (選填) 搜尋演算法的實作細節參數，此為一個 JSON Object 內含一系列的 key/value String | 無 |
| costWeights | (選填) 指定要優化的目標以及權重 | ReplicaSizeCost,ReplicaLeaderCost權重皆為1 |
| maxMigratedSize | (選填) 設定最大可搬移的log size | 無 　 |
Expand Down Expand Up @@ -58,21 +58,21 @@ curl -X POST http://localhost:8001/balancer \
```

JSON Response 範例
- `id`: 這個負載平衡計劃的編號，後續可以透過這個編號來查詢此計劃的狀態。
- `id`: 這個負載優化計劃的編號，後續可以透過這個編號來查詢此計劃的狀態。

```json
{
"id": "46ecf6e7-aa28-4f72-b1b6-a788056c122a"
}
```

> ##### 搜尋負載平衡計劃需要時間
> ##### 搜尋負載優化計劃需要時間
> 透過 `POST /balancer` 發起搜尋後，由於演算法邏輯和叢集效能資訊收集因素，這個計劃可能會花上一段時間才會找到。
> `POST /balancer` 回傳的計劃 id 能夠透過 [GET /balancer/{id}](#查詢負載平衡計劃的狀態) 查詢其搜尋狀態，
> `POST /balancer` 回傳的計劃 id 能夠透過 [GET /balancer/{id}](#查詢負載優化計劃的狀態) 查詢其搜尋狀態，
> 如果其 response 欄位 `generated` 為 `true`，則代表此計劃已經完成搜尋，能夠被 `PUT /balancer` 執行。
> 嘗試執行一個還沒完成搜尋的負載平衡計劃會發生錯誤。
> 嘗試執行一個還沒完成搜尋的負載優化計劃會發生錯誤。

## 執行負載平衡計劃
## 執行負載優化計劃

```shell
PUT /balancer
Expand All @@ -90,26 +90,26 @@ JSON Request 格式

| 名稱 | 說明 | 預設值 |
|-----|--------------------|-----|
| id | (必填) 欲執行的負載平衡計劃之編號 | 無 |
| id | (必填) 欲執行的負載優化計劃之編號 | 無 |

JSON Response 範例

* `id`: 被接受的負載平衡計劃編號。
* `id`: 被接受的負載優化計劃編號。

```json
{ "id": "46ecf6e7-aa28-4f72-b1b6-a788056c122a" }
```

後續能用特定 [API](#查詢負載平衡計劃的狀態) 來查詢負載平衡計劃的執行進度。
後續能用特定 [API](#查詢負載優化計劃的狀態) 來查詢負載優化計劃的執行進度。

> ##### 一個叢集同時間只能執行一個負載平衡計劃
> 嘗試對一個叢集同時套用多個負載平衡計劃會導致意外的結果，因此 `PUT /balancer` 被設計為：
> 同時間只能夠執行一個負載平衡計劃，嘗試執行多個負載平衡計劃，那只有一個請求會被接受，其他請求將會被拒絕。
> ##### 一個叢集同時間只能執行一個負載優化計劃
> 嘗試對一個叢集同時套用多個負載優化計劃會導致意外的結果，因此 `PUT /balancer` 被設計為：
> 同時間只能夠執行一個負載優化計劃，嘗試執行多個負載優化計劃，那只有一個請求會被接受，其他請求將會被拒絕。
> 注意 Web Service 只能夠避免對當前執行 process 的多個執行請求做有效預防。在執行計劃前 Web Service
> 會檢查是否有正在進行的 Partition Reassignment，如果有偵測到則意味着可能有其他負載平衡計劃正在運行。
> Web Service 在這個情況下也會拒絕執行負載平衡計劃。
> 會檢查是否有正在進行的 Partition Reassignment，如果有偵測到則意味着可能有其他負載優化計劃正在運行。
> Web Service 在這個情況下也會拒絕執行負載優化計劃。

## 查詢負載平衡計劃的狀態
## 查詢負載優化計劃的狀態

```shell
GET /balancer/{id}
Expand All @@ -124,28 +124,28 @@ curl -X GET http://localhost:8001/balancer/46ecf6e7-aa28-4f72-b1b6-a788056c122a

| 名稱 | 說明 | 預設值 |
|-----|--------------------|-----|
| id | (必填) 欲查詢的負載平衡計劃之代號 | 無 |
| id | (必填) 欲查詢的負載優化計劃之代號 | 無 |

> 目前實作不保留 web service 程式過去啟動時所接受的負載平衡計劃進度與結果
> 目前實作不保留 web service 程式過去啟動時所接受的負載優化計劃進度與結果

> 當查詢的 `id` 沒有對應到任何負載平衡計劃，回傳的 HTTP Status Code 會是 `404`
> 當查詢的 `id` 沒有對應到任何負載優化計劃，回傳的 HTTP Status Code 會是 `404`

JSON Response 範例

* `id`: 此 Response 所描述的負載平衡計劃之編號
* `phase`: 代表此負載平衡計劃狀態的字串，可能是下列任一值
* `Searching`: 正在搜尋能使叢集變更好的負載平衡計劃
* `id`: 此 Response 所描述的負載優化計劃之編號
* `phase`: 代表此負載優化計劃狀態的字串，可能是下列任一值
* `Searching`: 正在搜尋能使叢集變更好的負載優化計劃
* `Searched`: 計劃搜尋已經結束
* `Executing`: 正在將負載平衡計劃套用至叢集
* `Executed`: 此負載平衡計劃已經成功套用至叢集
* `exception`: 當負載平衡計劃發生結束時，其所附帶的錯誤訊息。如果沒有錯誤，此欄位會是 `null`，可能觸發錯誤的時間點包含：
1. 搜尋負載平衡計劃的過程中發生錯誤 (此情境下 `phase` 會是 `Searched`)
2. 執行負載平衡計劃的過程中發生錯誤 (此情境下 `phase` 會是 `Executed`)
* `Executing`: 正在將負載優化計劃套用至叢集
* `Executed`: 此負載優化計劃已經成功套用至叢集
* `exception`: 當負載優化計劃發生結束時，其所附帶的錯誤訊息。如果沒有錯誤，此欄位會是 `null`，可能觸發錯誤的時間點包含：
1. 搜尋負載優化計劃的過程中發生錯誤 (此情境下 `phase` 會是 `Searched`)
2. 執行負載優化計劃的過程中發生錯誤 (此情境下 `phase` 會是 `Executed`)
* `config` 此優化計劃的搜尋參數設定
* `balancer`: 此計劃生成所使用的搜尋算法實作
* `function`: 用來評估叢集狀態之品質的方法
* `timeoutMs`: 此優化計劃的搜尋上限時間
* `plan`: 此負載平衡計劃的詳細資訊，如果此計劃還沒完成搜尋，或是已經完成搜尋但找不到可用的計劃，則此欄位會是 `null`
* `plan`: 此負載優化計劃的詳細資訊，如果此計劃還沒完成搜尋，或是已經完成搜尋但找不到可用的計劃，則此欄位會是 `null`
* `changes`: 新的 partitions 配置
* `topic`: topic 名稱
* `partition`: partition id
Expand Down Expand Up @@ -201,7 +201,7 @@ JSON Response 範例

> ##### `before` 和 `after` 陣列中的位置存在特別含義
> `before` 和 `after` 欄位用 JSON 陣列描述一個 topic/partition 預期的 replica 分佈狀況，
> 其中第一個欄位會被解釋成特定 topic/partition 的 preferred leader，且在負載平衡執行後，
> 其中第一個欄位會被解釋成特定 topic/partition 的 preferred leader，且在負載優化執行後，
> 這個 preferred leader 會被內部計劃的執行邏輯變更為當前 partition 的 leader。
>
> 從 JSON 陣列第二位開始預期都是這個 topic/partition 的 follower logs，特別注意目前內部實作
Expand All @@ -215,14 +215,14 @@ JSON Response 範例
> 2. 節點輸出流量 weight 1
> 3. 節點的 Leader 數量 weight 1
>
> 上述在進行負載優化時，由於 Leader 的平衡和網路吞吐量一樣重要，可能會導致為了多兼容這個優化需求而喪失一些優化的機會。
> 上述在進行負載優化時，由於 Leader 的優化和網路吞吐量一樣重要，可能會導致為了多兼容這個優化需求而喪失一些優化的機會。
> 如發現 Balancer 生成計劃的 `newScore` 分數沒辦法貼近 0，則其生成的計劃可能在三者之間做了某種程度的取捨。如果不希望
> 這些取捨發生，或願意對某些不重要的優化項目做取捨，可以考慮調低 Leader 數量平衡的權重值。
> 這些取捨發生，或願意對某些不重要的優化項目做取捨，可以考慮調低 Leader 數量優化的權重值。

> ##### 解讀 `score` 的注意事項
> 1. `score` 和 `newScore` 之值代表一個叢集分佈接近最佳狀況的程度。
> 2. 不同負載平衡計劃之間的 `score` 分數沒有關聯(不能彼此比較)。
> 3. 同一筆平衡計劃所產生分數能夠反映叢集的好壞，即 `scoreA` > `scoreB` 有定義，其代表 B 負載分佈比 A 負載分佈在此特定情境下更好。
> 2. 不同負載優化計劃之間的 `score` 分數沒有關聯(不能彼此比較)。
> 3. 同一筆優化計劃所產生分數能夠反映叢集的好壞，即 `scoreA` > `scoreB` 有定義，其代表 B 負載分佈比 A 負載分佈在此特定情境下更好。


目前此 endpoint 僅能查詢負載平衡計劃是否完成，如想知道更細部的搬移進度，可考慮使用 [Web Service Reassignments API](web_api_reassignments_chinese.md) 查詢。
目前此 endpoint 僅能查詢負載優化計劃是否完成，如想知道更細部的搬移進度，可考慮使用 [Web Service Reassignments API](web_api_reassignments_chinese.md) 查詢。