throttle.module 13.8 KB
Newer Older
Dries's avatar
 
Dries committed
1
<?php
Dries's avatar
 
Dries committed
2
// $Id$
Dries's avatar
 
Dries committed
3

Dries's avatar
 
Dries committed
4 5 6 7 8
/**
 * @file
 * Allows configuration of congestion control auto-throttle mechanism.
 */

Dries's avatar
Dries committed
9 10 11 12 13
/**
 * Determine the current load on the site.
 *
 * Call the throttle_status() function from your own modules, themes, blocks,
 * etc. to determine the current throttle status. For example, in your theme
Dries's avatar
 
Dries committed
14 15 16
 * you might choose to disable pictures when your site is too busy (reducing
 * bandwidth), or in your modules you might choose to disable some complicated
 * logic when your site is too busy (reducing CPU utilization).
Dries's avatar
Dries committed
17 18 19 20 21
 *
 * @return
 *   A number from 0 to 5.  0 means that the current load is very small; 5
 *   means that the current load is as heavy as it gets.  You should
 *   consider disabling logic when the throttle level gets to 4 or 5.
Dries's avatar
 
Dries committed
22 23
 */
function throttle_status() {
Dries's avatar
 
Dries committed
24
  return variable_get('throttle_level', 0);
Dries's avatar
 
Dries committed
25 26
}

Dries's avatar
Dries committed
27 28 29 30 31
/**
 * Implementation of hook_exit().
 *
 * Changes the current throttle level based on page hits.
 */
Dries's avatar
 
Dries committed
32
function throttle_exit() {
Dries's avatar
Dries committed
33 34 35 36 37 38 39 40 41 42 43 44 45
  // The following logic determines what the current throttle level should
  //  be, and can be disabled by the admin.  If enabled, the rand() function
  //  returns a number between 0 and N, N being specified by the admin. If
  //  0 is returned, the throttle logic is run, adding on additional database
  //  query.  Otherwise, the following logic is skipped.  This mechanism is
  //  referred to in the admin page as the 'probability limiter', roughly
  //  limiting throttle related database calls to 1 in N.
  if (!rand(0, variable_get('throttle_probability_limiter', 9))) {
    // Note:  The rand() function is supported by PHP 3+.  However, prior to
    // PHP 4.2.0 it needs to be seeded with a call to srand().  It is important
    // that this only happens once, so this should be managed by the Drupal
    // engine, not this module.  The Drupal engine should use phpversion() to
    // detect and automatically seed pre-4.2.0 systems.
Dries's avatar
 
Dries committed
46 47

    $throttle = throttle_status();
Dries's avatar
Dries committed
48
    $multiplier = variable_get('throttle_multiplier', 60);
Dries's avatar
Dries committed
49 50
    // Count all hits in the past sixty seconds.
    $recent_activity = db_fetch_object(db_query('SELECT COUNT(timestamp) AS hits FROM {accesslog} WHERE timestamp >= %d', (time() - 60)));
Dries's avatar
 
Dries committed
51
    _throttle_update($recent_activity->hits);
Dries's avatar
 
Dries committed
52 53 54
  }
}

Dries's avatar
Dries committed
55 56 57
/**
 * Implementation of hook_perm().
 */
Dries's avatar
 
Dries committed
58
function throttle_perm() {
Dries's avatar
Dries committed
59
  return array('access throttle block');
Dries's avatar
 
Dries committed
60 61
}

Dries's avatar
Dries committed
62 63 64 65
/**
 * Implementation of hook_help().
 */
function throttle_help($section) {
Dries's avatar
 
Dries committed
66
  switch ($section) {
Dries's avatar
 
Dries committed
67
    case 'admin/modules#description':
Dries's avatar
Dries committed
68
      return t('Allows configuration of congestion control auto-throttle mechanism.');
69
    case 'admin/settings/throttle':
70
      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 log must be enabled.  It is advised that you carefully read the explanations below and then properly tune this module based on your site\'s requirements and your webserver\'s capabilities.', array('%access' => url('admin/modules/statistics')));
Dries's avatar
Dries committed
71 72
    case 'admin/help#throttle':
      return t("
Dries's avatar
 
Dries committed
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92
      <h3>Introduction</h3>
      <p>This Drupal module allows you to enable and configure the auto-throttle congestion control mechanism offered by the <a href=\"%statistics-module\">statistics module</a>.  The auto-throttle mechanism allows your site to automatically adapt to different server levels.</p>
      <p>This module also adds a block that displays the current status of the throttle.  You must have \"<a href=\"%throttle-block\">access throttle block</a>\" privileges to view the block.  As a general rule of thumb, only site administrators should be granted access to this block.</p>
      <p>The auto-throttle mechanism performs an extra database query in order to determine what the current throttle level should be.  Fortunately the throttle can be tuned so these database queries only occur on a fraction of all pages generated by your site, reducing the overhead to an insignificant amount.  Additionally, when the top-most throttle level is reached, all throttle queries are suspended for a configurable period of time.  More detail follows.</p>
      <p>As with any module, the throttle module needs to be <a href=\"%modules-enable\">enabled</a> before you can use it.  Also refer to the permissions section below if you wish to access the throttle statistics block.</p>
      <h3>Configuring the throttle module</h3>
      <p>The <a href=\"%throttle-config\">configuration section</a> for the throttle allows you to turn it on and off, as well as to fine-tune how sensitive it is.</p>
      <h4>enable auto-throttle:</h4>
      <blockquote>This first option on the throttle module configuration screen allows you to enable or disable the auto-throttling mechanism.  Note that the access-log must also be enabled via the <a href=\"%statistics-config\">statistics module</a> for the auto-throttling mechanism to have any effect.</blockquote>
      <h4>auto-throttle multiplier:</h4>
      <blockquote><p>This second option allows you to tune the auto-throttle mechanism.  The auto-throttle mechanism supports six throttle levels, from 0 (off) to 5 (maximum).  The current throttle level is based upon how many pages have been accessed on your site in the past 60 seconds - the more pages being displayed, the higher the throttle level.  This multiplier defines how many hits are required to switch from one throttle level to the next.</p>
      <p>For example, with a throttle multiplier of 20:  Once 20 pages have been accessed on your site within a period of 60 seconds, the throttle level will be incremented to a level of 1.  Once 40 pages have been accessed on your site within a period of 60 seconds, the throttle level will be incremented to a level of 2.  And so on, until 100 pages are accessed on your site within a period of 60 seconds, at which time the throttle level will be set to a maximum level of 5.</p></blockquote>
      <h4>auto-throttle probability limiter:</h4>
      <blockquote><p>This option allows you to minimize the performance impact of the auto-throttle.  If we refer to the probability limiter as P, then P% of all pages generated by your site will perform an extra database query to verify that the current throttle level is appropriate to the current server load.</p>
      <p>As a rule of thumb, the higher your multiplier, the lower your probability limiter should be.  For example, if you have a multiplier of 100, then you logically don't need to check the throttle level more than once out of every 100 page views, so the probability limiter should be set to 1%.  As database queries are \"expensive\", it's recommended that you keep the probability limiter to the smallest percentage possible, while still high enough to react quickly to a change in server load.</p></blockquote>
      <h3>Throttle block</h3>
      <p>This block displays some statistics regarding the current throttle and its configuration.  It is recommended that only site administrators receive the \"<a href=\"%throttle-access\">access throttle block</a>\" permission bit required to view this block.  It does not display information that would interest a normal site end-user.</p>
      <p>Don't forget to <a href=\"%throttle-block-enable\">enable the block</a>.</p>
      <h3>Permissions</h3>
      <p>This module has one permission that needs to be configured in <a href=\"%permissions\">user permissions</a>.</p>
93
      <ul><li><em>access throttle block</em> - enable for user roles that get to view the throttle block.</li></ul>
Dries's avatar
 
Dries committed
94 95 96 97
      <h3>For programmers: throttle_status()</h3>
      <p>The function <code>throttle_status()</code> will return a number from 0 to 5.  0 means that there is no throttle enabled at this time.  Each number above that is a progressively more throttled system...  To disable a feature when a site first begins to get busy, disable it at a throttle of 2 or 3.  To hold on to the bitter end, wait until 4 or 5.</p>
      <p>To implement the throttle, you should do something like this:
      <pre>
98 99
       if (module_invoke(\"throttle\", \"status\") >= \$my_throttle_value) {
          // my throttle limit was reached, disable stuff
Dries's avatar
 
Dries committed
100 101 102
        }
        else {
          // throttle limit not reached, execute normally
Dries's avatar
 
Dries committed
103
       }</pre>
104
      </p>", array('%statistics-module' => url('admin/statistics'), '%throttle-block' => url('admin/user/configure/permission'), '%modules-enable' => url('admin/modules'), '%throttle-config' => url('admin/settings/throttle'), '%statistics-config' => url('admin/modules/statistics'), '%throttle-access' => url('admin/user/configure/permission'), '%throttle-block-enable' => url('admin/block'), '%permissions' => url('admin/user/configure/permission')));
Dries's avatar
 
Dries committed
105
  }
Dries's avatar
 
Dries committed
106 107
}

Dries's avatar
Dries committed
108 109 110
/**
 * Implementation of hook_settings().
 */
111
function throttle_settings() {
Dries's avatar
Dries committed
112 113
  // 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)');
114
  $group = form_select(t('Auto-throttle multiplier'), 'throttle_multiplier', variable_get('throttle_multiplier', 60), $throttles, t('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.'));
Dries's avatar
Dries committed
115
  $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%');
116
  $group .= form_select(t('Auto-throttle probability limiter'), 'throttle_probability_limiter', variable_get('throttle_probability_limiter', 9), $probabilities, t('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.'));
Dries's avatar
Dries committed
117 118
  $period = drupal_map_assoc(array(1800, 3600, 7200, 10800, 14400, 18000, 21600, 43200, 64800, 86400, 172800, 259200, 604800), 'format_interval');
  $output .= form_group(t('Auto-throttle tuning'), $group);
Dries's avatar
 
Dries committed
119

Dries's avatar
 
Dries committed
120 121 122
  return $output;
}

Dries's avatar
Dries committed
123 124 125
/**
 * Displays admin-oriented "Throttle status" block.
 */
Dries's avatar
 
Dries committed
126
function throttle_display_throttle_block() {
Dries's avatar
Dries committed
127
  if (user_access('access throttle block')) {
Dries's avatar
Dries committed
128 129
    // The throttle is enabled:  display the status of all throttle config.
    $throttle = module_invoke('throttle', 'status');
Dries's avatar
 
Dries committed
130 131
    $multiplier = variable_get('throttle_multiplier', 60);
    $minimum = $throttle * $multiplier;
Dries's avatar
Dries committed
132 133
    $limiter = variable_get('throttle_probability_limiter', 9);
    // Calculate probability limiter's odds of updating the throttle level.
Dries's avatar
 
Dries committed
134 135 136 137
    $probability = substr((($limiter / ($limiter + 1) * 100) - 100) * -1, 0, 4);

    if ($throttle < 5) {
      $maximum = (($throttle + 1) * $multiplier) - 1;
Dries's avatar
Dries committed
138
      $output .= t('Current level: %level (%min - %max)', array('%level' => $throttle, '%min' => $minimum, '%max' => $maximum)) ."<br />\n";
Dries's avatar
 
Dries committed
139 140
    }
    else {
Dries's avatar
Dries committed
141
      $output .= t('Current level: %level (%min+)', array('%level' => $throttle, '%min' => $minimum)) ."<br />\n";
Dries's avatar
 
Dries committed
142
    }
Dries's avatar
Dries committed
143
    $output .= t('Probability: %probability%', array('%probability' => $probability)) ."<br />\n";
Dries's avatar
 
Dries committed
144
    if ($throttle < 5) {
Dries's avatar
Dries committed
145 146
      $recent_activity = db_fetch_object(db_query('SELECT COUNT(timestamp) AS hits FROM {accesslog} WHERE timestamp >= %d', (time() - 60)));
      $output .= '<br />'. t('This site has served %pages pages in the past minute.', array('%pages' => format_plural($recent_activity->hits , '1 page', '%count pages')));
Dries's avatar
 
Dries committed
147
      _throttle_update($recent_activity->hits);
Dries's avatar
 
Dries committed
148 149 150 151 152
    }
  }
  return $output;
}

Dries's avatar
Dries committed
153 154 155 156 157 158
/**
 * Implementation of hook_block().
 */
function throttle_block($op = 'list', $delta = 0) {
  if ($op == 'list') {
    $blocks[0]['info'] = t('Throttle status');
Dries's avatar
 
Dries committed
159 160
    return $blocks;
  }
161
  else if ($op == 'view') {
Dries's avatar
Dries committed
162 163
    $block['subject'] = t('Throttle status');
    $block['content'] = throttle_display_throttle_block();
Dries's avatar
 
Dries committed
164 165
    return $block;
  }
Dries's avatar
 
Dries committed
166 167
}

Dries's avatar
 
Dries committed
168 169
function _throttle_update($hits) {
  $throttle = throttle_status();
Dries's avatar
Dries committed
170
  $multiplier = variable_get('throttle_multiplier', 60);
Dries's avatar
 
Dries committed
171 172

  for ($i = 0; $i <= 5; $i++) {
Dries's avatar
 
Dries committed
173
    if ($i * $multiplier <= $hits) {
Dries's avatar
 
Dries committed
174 175 176 177
      $throttle_new = $i;
    }
  }

178 179
  $type = $throttle_new > 2 ? 'warning' : 'regular';

Dries's avatar
 
Dries committed
180 181
  // log the change
  if ($throttle_new < $throttle) {
Dries's avatar
Dries committed
182
    variable_set('throttle_level', $throttle - 1);
Dries's avatar
 
Dries committed
183
    watchdog($type, t('Throttle: %hits hits in past minute; throttle decreased to level %level.', array('%hits' => "<em>$hits</em>", '%level' => '<em>'. ($throttle - 1) .'</em>')));
Dries's avatar
 
Dries committed
184 185
  }
  if ($throttle_new > $throttle) {
Dries's avatar
Dries committed
186
    variable_set('throttle_level', $throttle + 1);
Dries's avatar
 
Dries committed
187
    watchdog($type, t('Throttle: %hits hits in past minute; throttle increased to level %level.', array('%hits' => "<em>$hits</em>", '%level' => '<em>'. ($throttle + 1) .'</em>')));
Dries's avatar
 
Dries committed
188 189 190
  }
}

Dries's avatar
 
Dries committed
191
?>