- Throttle module improvements by Jeremy:

   + Fix modules help to read better and be accurate
   + Add groups to throttle_settings()
   + Provide much more detailed information in all _settings options
   + Fix links in module's "Throttle status" block

1 files changed, 13 insertions, 8 deletions

diff --git a/modules/throttle.module b/modules/throttle.module
index d6b3b7df5..9c55e37b2 100644
--- a/modules/throttle.module
+++ b/modules/throttle.module
@@ -16,7 +16,7 @@ function throttle_help($section = "admin/help#throttle") {
       $output = t("Allows configuration of congestion control auto-throttle mechanism.");
       break;
     case "admin/system/modules/throttle":
-      return t("If your site gets popular, or comes under a \"Denial of Service\" (DOS) attack, your hardware might become overwhelmed. These settings allow you to \"slow down\" the access to your site. To use throttle you need to have the %access enabled. For Drupal to preform throttling it needs to do an extra database query. This extra query happens on page displays. <b>Auto-throttle probability limiter</b> tells Drupal to do this extra DB query once every \"x\" page displays, where \"x\" is the percentage. So if it is set to 10%, the default, then for every 100 web pages it displays, it will preform the extra query ten time. ", array("%access" => l(t("access log"), "admin/system/modules/statistics")));
+      return t("If your site gets linked to by a popular website, or otherwise comes under a \"Denial of Service\" (DoS) attack, your webserver might become overwhelmed.  This module provides a mechanism for automatically detecting a surge in incoming traffic.  This mechanism is utilized by other Drupal models to automatically optimize their performance by temporarily disabling CPU-intensive functionality.  To use the auto-throttle, the %access must be enabled.  It is advised that you carefully read the explainations below and then properly tune this module based on your site's requirements and your webserver's capabilities.", array("%access" => l(t("access log"), "admin/system/modules/statistics")));
     case "admin/help#throttle":
       $output .= "<h3>Introduction</h3><p>This Drupal module allows you to enable and configure the auto-throttle congestion control mechanism offered by the %statistics-module.  The auto-throttle mechanism allows your site to automatically adapt to different server levels.</p>";
       $output .= "<p>This module also adds a block that displays the current status of the throttle.  You must have \"%throttle-block\" privileges to view the block.  As a general rule of thumb, only site administrators should be granted access to this block.</p>";
@@ -58,14 +58,19 @@ function throttle_help($section = "admin/help#throttle") {
 
 /* Adds configure option to the main configure site admin page */
 function throttle_settings() {
-  /* access log options */
-  $output .= form_radios(t("Enable auto-throttle"), "statistics_enable_auto_throttle", variable_get("statistics_enable_auto_throttle", 0), array("1" => t("enabled"), "0" => t("disabled")), "Enable auto-throttling congestion control mechanism.  Allows your site to adapt under extreme user loads.  Requires that 'access log' be enabled.");
+  // enable/disable auto-throttle
+  $group = form_radios(t("Enable auto-throttle"), "statistics_enable_auto_throttle", variable_get("statistics_enable_auto_throttle", 0), array("1" => t("enabled"), "0" => t("disabled")), "Enable auto-throttling congestion control mechanism.  Allows your site to adapt under extreme user loads, such as being linked by Slashdot.  To use the auto-throttle you must also enable the 'access log' from the statistics module.");
+  $output = form_group(t("Enable/Disable"), $group);
+
+  // tune auto-throttle
   $throttles = array(1 => "1 (0,1,2,3,4,5)", 5 => "5 (0,5,10,15,20,25)", 10 => "10 (0,10,20,30,40,50)", 12 => "12 (0,12,24,36,48,60)", 15 => "15 (0,15,30,45,60,75)", 20 => "20 (0,20,40,60,80,100)", 30 => "30 (0,30,60,90,120,150)", 50 => "50 (0,50,100,150,200,250)", 60 => "60 (0,60,120,180,240,300)", 100 => "100 (0,100,200,300,400,500", 500 => "500 (0,500,1000,1500,2000,2500", 1000 => "1000 (0,1000,2000,3000,4000,5000)");
-  $output .= form_select(t("Auto-throttle multiplier"), "statistics_throttle_multiplier", variable_get("statistics_throttle_multiplier", 60), $throttles, "Throttle tuning.  Specify how many hits in the past 60 seconds triggers higher throttle level.  Example: multiplier of 5 takes 5 hits for level 1, 25 hits for level 5.");
+  $group = form_select(t("Auto-throttle multiplier"), "statistics_throttle_multiplier", variable_get("statistics_throttle_multiplier", 60), $throttles, "The 'auto-throttle multiplier' is the number of hits in the past 60 seconds required to trigger a higher throttle level.  For example, if you set the multiplier to 60, and your site is getting less than 60 hits a minute, then the throttle will be at a level of 0.  Only once you start getting more than 60 hits a minute will the throttle level go to 1.  If you start getting more than 120 hits a minute, the throttle becomes 2.  This continues until your site is sustaining more than 300 hits per minute, at which time the throttle reaches a maximum level of 5.  In the pop down menu, the first number is the multiplier, and the numbers in parenthesis are how many hits are required to switch to each throttle level.  The more powerful your server, the higher you should set the multiplier value.");
   $probabilities = array(0 => "100%", 1 => "50%", 2 => "33.3%", 3 => "25%", 4 => "20%", 5 => "16.6%", 7 => "12.5%", 9 => "10%", 19 => "5%", 99 => "1%", 199 => ".5%", 399 => ".25%", 989 => ".1%");
-  $output .= form_select(t("Auto-throttle probability limiter"), "statistics_probability_limiter", variable_get("statistics_probability_limiter", 9), $probabilities, "Throttle tuning.  Probability based efficiency mechanism specifying the probability, expressed in a percentage of page views, an extra database query is performed to adjust throttle level.");
+  $group .= form_select(t("Auto-throttle probability limiter"), "statistics_probability_limiter", variable_get("statistics_probability_limiter", 9), $probabilities, "The auto-throttle probability limiter is an efficiency mechanism to statistically reduce the overhead of the auto-throttle.  The limiter is expressed as a percentage of page views, so for example if set to the default of 10% we only perform the extra database query to update the current level 1 out of every 10 page views.  The busier your site, the lower you should set the limiter value.");
   $period = array(1800 => format_interval(1800), 3600 => format_interval(3600), 7200 => format_interval(7200), 10800 => format_interval(10800), 14400 => format_interval(14400), 18000 => format_interval(18000), 21600 => format_interval(21600), 43200 => format_interval(43200), 64800 => format_interval(64800), 86400 => format_interval(86400), 172800 => format_interval(172800), 259200 => format_interval(259200), 604800 => format_interval(604800));
-  $output .= form_select(t("Auto-throttle cron test"), "statistics_throttle_cron_timer", variable_get("statistics_throttle_cron_timer", 10800), $period, "Throttle tuning.  Specify how often cron should drop the thottle level (if up) to test server load.  Requires cron.");
+  $group .= form_select(t("Auto-throttle cron test"), "statistics_throttle_cron_timer", variable_get("statistics_throttle_cron_timer", 10800), $period, "The auto-throttle cron test value specifies how frequently the throttle level will be automatically lowered, testing server load.  After this amount of time, if your throttle level is greater than 0, it will be reduced by 1.  If your site is no longer sustaining as heavy a load as it was when it increased the throttle, it will stay at this reduced level.  If your site is still sustaining a heavy load, the throttle level will soon be increased again.  Requires cron.");
+  $output .= form_group(t("Auto-throttle tuning"), $group);
+
   return $output;
 }
 
@@ -89,7 +94,7 @@ function throttle_display_throttle_block() {
       /* calculate probability limiter's odds of updating throttle */
       $probability = substr((($limiter / ($limiter + 1) * 100) - 100) * -1, 0, 4);
 
-      $output .= "Throttle: ". l("Enabled", "admin/system#statistics") ."<br />\n";
+      $output .= "Throttle: ". l("Enabled", "admin/system/modules/throttle") ."<br />\n";
       if ($throttle < 5) {
         $maximum = (($throttle + 1) * $multiplier) - 1;
         $output .= "Current Level: $throttle ($minimum - $maximum)<br />\n";
@@ -105,7 +110,7 @@ function throttle_display_throttle_block() {
       }
     }
     else {
-      $output .= "Throttle: ". l("Disabled", "admin/system#statistics") ."<br />\n";
+      $output .= "Throttle: ". l("Disabled", "admin/system/modules/throttle") ."<br />\n";
     }
   }
   return $output;