[pulsar] branch master updated: [Docs][LoadBalancing] Add/Improve Javadocs for LoadSheddingStrategy impls (#12180)

[li...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

liuyu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git


The following commit(s) were added to refs/heads/master by this push:
     new 41ea8b9  [Docs][LoadBalancing] Add/Improve Javadocs for LoadSheddingStrategy impls (#12180)
41ea8b9 is described below

commit 41ea8b9924df442b934fed90391c43ddb45e9996
Author: Michael Marshall <mi...@gmail.com>
AuthorDate: Tue Sep 28 19:38:04 2021 -0500

    [Docs][LoadBalancing] Add/Improve Javadocs for LoadSheddingStrategy impls (#12180)
    
    * [LoadBalancing] Add/Improve Javadocs for LoadSheddingStrategy impls
    
    * Use present tense
    
    Co-authored-by: Anonymitaet <50...@users.noreply.github.com>
    
    Co-authored-by: Anonymitaet <50...@users.noreply.github.com>
---
 .../pulsar/broker/loadbalance/impl/OverloadShedder.java      | 11 +++++++----
 .../pulsar/broker/loadbalance/impl/ThresholdShedder.java     | 12 ++++++++++++
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/loadbalance/impl/OverloadShedder.java b/pulsar-broker/src/main/java/org/apache/pulsar/broker/loadbalance/impl/OverloadShedder.java
index 89e3204..67e10dc 100644
--- a/pulsar-broker/src/main/java/org/apache/pulsar/broker/loadbalance/impl/OverloadShedder.java
+++ b/pulsar-broker/src/main/java/org/apache/pulsar/broker/loadbalance/impl/OverloadShedder.java
@@ -35,11 +35,14 @@ import org.slf4j.LoggerFactory;
 
 /**
  * Load shedding strategy which will attempt to shed exactly one bundle on brokers which are overloaded, that is, whose
- * maximum system resource usage exceeds loadBalancerBrokerOverloadedThresholdPercentage. A bundle will be recommended
- * for unloading off that broker if and only if the following conditions hold: The broker has at least two bundles
- * assigned and the broker has at least one bundle that has not been unloaded recently according to
+ * maximum system resource usage exceeds loadBalancerBrokerOverloadedThresholdPercentage. To see which resources are
+ * considered when determining the maximum system resource, see {@link LocalBrokerData#getMaxResourceUsage()}. A bundle
+ * is recommended for unloading off that broker if and only if the following conditions hold: The broker has at
+ * least two bundles assigned and the broker has at least one bundle that has not been unloaded recently according to
  * LoadBalancerSheddingGracePeriodMinutes. The unloaded bundle will be the most expensive bundle in terms of message
- * rate that has not been recently unloaded.
+ * rate that has not been recently unloaded. Note that this strategy does not take into account "underloaded" brokers
+ * when determining which bundles to unload. If you are looking for a strategy that spreads load evenly across
+ * all brokers, see {@link ThresholdShedder}.
  */
 public class OverloadShedder implements LoadSheddingStrategy {
 
diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/loadbalance/impl/ThresholdShedder.java b/pulsar-broker/src/main/java/org/apache/pulsar/broker/loadbalance/impl/ThresholdShedder.java
index f33ad9c..a8e6edf 100644
--- a/pulsar-broker/src/main/java/org/apache/pulsar/broker/loadbalance/impl/ThresholdShedder.java
+++ b/pulsar-broker/src/main/java/org/apache/pulsar/broker/loadbalance/impl/ThresholdShedder.java
@@ -35,6 +35,18 @@ import org.apache.pulsar.policies.data.loadbalancer.LocalBrokerData;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * Load shedding strategy that unloads any broker that exceeds the average resource utilization of all brokers by a
+ * configured threshold. As a consequence, this strategy tends to distribute load among all brokers. It does this by
+ * first computing the average resource usage per broker for the whole cluster. The resource usage for each broker is
+ * calculated using the following method: {@link LocalBrokerData#getMaxResourceUsageWithWeight)}. The weights for each
+ * resource are configurable. Historical observations are included in the running average based on the broker's
+ * setting for loadBalancerHistoryResourcePercentage. Once the average resource usage is calculated, a broker's
+ * current/historical usage is compared to the average broker usage. If a broker's usage is greater than the average
+ * usage per broker plus the loadBalancerBrokerThresholdShedderPercentage, this load shedder proposes removing
+ * enough bundles to bring the unloaded broker 5% below the current average broker usage. Note that recently
+ * unloaded bundles are not unloaded again.
+ */
 public class ThresholdShedder implements LoadSheddingStrategy {
     private static final Logger log = LoggerFactory.getLogger(ThresholdShedder.class);