<p>This Drupal module keeps track of numerous statistics for your site. Be warned, statistical collection does cause a little overhead, thus everything is disabled by default when this module is first installed.</p>
<p>The statistics module counts how many times each of your nodes is viewed, also tracking where each link to the node came from (HTTP referrer). The number of times a node has been viewed can be displayed in the node's link section (next to "# comments" etc).</p>
<p>This module also adds a configurable block that can display the day's top stories, the all time top stories, and the last stories read. Each of these supports a configurable header and number of stories.</p>
<p>This module also adds a configurable user page that can display the day's top stories, the all time top stories, and the last stories read. Each of these supports a configurable header and number of stories.</p>
<p>This module also adds a configurable block that displays counts of how many users and guests are currently accessing your site, as well as a list of the names of the users currently accessing your site.</p>
<p>This module also adds an admin viewable block that displays the current status of the throttle. You must have "administer site configuration" priveleges to view the block.</p>
<p>If you enable the node counters, this adds 1 database query for each node that is viewed (2 queries if it's the first time the node has ever been viewed).</p>
<p>If you enable the access log, this adds 1 database query for each page that Drupal displays. Logged information includes: HTTP referrer (if any), node being accessed (if any), user ID (if any), the IP address of the user, and the time the page was viewed.</p>
<p>If you enable the auto-throttle, this adds 1 database query for each page that is displayed (until the maximum throttle is reached, then the query is automatically disabled until the site is less busy). This requires cron.</p>
<p><b>For efficiency, the statistics module requires the <code>mysql_affected_rows()</code> function, currently tieing it to MySQL.</b></p>
<p>As with any new module, <i>statistics.module</i> needs to be enabled <?php print l("here", array("mod" => "system", "op" => "modules"), "admin"); ?> before you can use it. Also refer to the permissions section below, as this module supports four separate permissions.</p>
<h3>MySQL table</h3>
<p>To use this module you need to create the 'statistics' and 'accesslog' MySQL tables. The easiest way to do this is with the included 'statistics.mysql' script. Type something like:
<pre> mysql -u<username> -p<password> <database> < statistics.mysql</pre></p>
<p>If you'd prefer to add the table manually, you can cut and paste the following lines into the MySQL command line:
<pre> DROP TABLE IF EXISTS statistics;
CREATE TABLE statistics (
nid int(11) NOT NULL,
totalcount bigint UNSIGNED DEFAULT '0' NOT NULL,
daycount mediumint UNSIGNED DEFAULT '0' NOT NULL,
timestamp int(11) UNSIGNED DEFAULT '0' NOT NULL,
PRIMARY KEY (nid),
INDEX (totalcount),
INDEX (daycount),
INDEX (timestamp)
);
DROP TABLE IF EXISTS accesslog;
CREATE TABLE accesslog (
nid int(11) UNSIGNED DEFAULT '0',
url varchar(255),
hostname varchar(128),
uid int(10) UNSIGNED DEFAULT '0',
timestamp int(11) UNSIGNED NOT NULL
);</pre></p>
<h3>View statistics</h3>
<p>This admin page gives you an at-a-glance look at your top nodes. It is useful for understanding what content on your Drupal site is the most popular. Also on this page are links to the referrer statistics for each listed node.</p>
<h3>View referrers</h3>
<p>This admin page shows you site-wide referrer statistics. You can see '<i>all</i>' stats, '<i>external</i>' statistics or '<i>internal</i>' stats. (Default is 'external')</p>
<h3>Configuring the statistics module</h3>
<p>There are a couple of configuration options added to the main <?php print l("site configuration", array("mod" => "system"), "admin"); ?> admin page.
<p>The first option, <i>enable access log</i>, allows you to turn the access log on and off. This log is used to store things like referrers and who's online. Enabling the log adds one database call per page displayed by Drupal.</p>
<p>The second option, <i>discard access logs older than</i>, allows you to configure how long an access log entry is saved, after which time it is deleted from the database table.</p>
<p>The third option, <i>enable auto-throttle</i>, allows you to turn the auto-throttle feature on and off. The access log must also be enabled for the auto-throttle to function.</p>
<p>The next option, <i>auto-throttle multiplier</i>, selects a multiplier to calculate each auto-throttle level. For example, with a multiplier of '10', level one starts when 10 users hit your site in 60 seconds, level 2 starts when 20 users hit your site in 60 seconds, so on up to level 5 which starts when 50 users hit your site in 60 seconds.</p>
<p>The next option, <i>auto-throttle probability limiter</i>, allows you to specify roughly how often the throttle level is updated. Each time it gets updated, it adds a database query to that pages generation, so it's a good idea to keep the probability limiter down at 20% or lower.</p>
<p>The next option, <i>enable node counter</i>, allows you to turn on and off the node-counting functionality of this module. If it is turned on, an extra database query is added for each node displayed, as a counter is incremented with each node view.</p>
<p>The next option, <i>display node counters</i>, allows you to globally disable the displaying of node counters. Additionally, a user group must have 'access statistics' permissions to view the counters.</p>
<p>The final option is to <i>reset the day counter</i>. Every twenty four hours, all the day's totals are automatically reset to 0, and started again. Whatever time you click this link is the time each day that the day's totals will be reset. This requires cron. Note that clicking this link will reload the site configuration page <i>without</i> saving any other changes you might have made.</p>
<h3>Top nodes block</h3>
<p>This module creates a block that can display the day's top viewed nodes, the all time top viewed nodes and the last nodes viewed. Each of these links can be enabled or disabled individually, and the number of nodes displayed for each can be configured with a drop down menu. If you disable all sections of this block, it will not appear.</p>
<p>The administrative "top nodes block" screen also allows you to assign a name to the block.</p>
<p>Don't forget to enable the block <?php print l("here", array("mod" => "block"), "admin"); ?>.</p>
<h3>Top nodes page</h3>
<p>This module creates a user page that can display summaries of the day's top viewed nodes, the all time top nodes and the last nodes viewed. Each of these summaries can be enabled or disabled individually, and the number of nodes displayed for each can be configured with a drop down menu.</p>
<p>The administrative "top nodes page" screen also allows you to assign a name for the automatically generated link to the user page. If no name is set, the link will not be displayed.</p>
<h3>Who's online block</h3>
<p>This module creates a block that can display how many user's and guests are currently online. You are able to configure the name of the block, the name of a sub-block for displaying names of user's currently online, how recently a user must have been active to be considered online, the maximum characters to display from a user's name and the maximum number of user names to display.</p>
<p>Don't forget to enable the block <?php print l("here", array("mod" => "block"), "admin"); ?>.</p>
<h3>Permissions</h3>
<p>This module has four permissions that need to be configured in
<li><i>access statistics</i> - enable for user roles that get to see individual node counts. (This does not define access to the block)</li>
<li><i>access userlist</i> - enable for user roles that get to see the list of user's that are currently online within the "Who's online" block.</li>
<li><i>administer statistics module</i> - enable for user roles that get to configure the statistics module.</li>
<li><i>administer stats</i> - enable for user roles that get to view the referrer statistics.</li>
</ul>
If '<i>administer stats</i>' and '<i>access statistics</i>' are both enabled, the user will see a link from each node to that node's referrer statistics (if enabled).
<hr>
<h2>Statistics for developers</h2>
<h3>Accessing statistics</h3>
<p>To get a node's view statistics make a call to the function <i>statistics_get($nid)</i>. When you pass in a $nid, the function returns an array with three entires: [0]=totalcount, [1]=daycount, [2]=timestamp. For example, you could use this function call to add node view counts to your theme.</p>
<ul>
<li>The <i>totalcount</i> is a count of the total number of times that node has been viewed.</li>
<li>The <i>daycount</i> is a count of the total number of times that node has been viewed "today". For the daycount to be reset, cron must be enabled.</li>
<li>The <i>timestamp</i> is a timestamp of when that node was last viewed.</li>
</ul>
<p>The module automatically adds '# reads' to each node's link section (if enabled).</p>
<h3>Top stories</h3>
<p>The statistics.module provides a function '<i>statistics_display_ltitle($type)</i>' to return a linked title of any of the following: the top viewed node of all time, the top viewed node of today, the last viewed node. You can pass in:
<ul>
<li><i>totalcount</i> - This will return a link to the top viewed node of all time.<br />
<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> $throttle = 0;
/* verify that the statitistics module is installed */
"stats b1 max names" => variable_get("stats b1 max names", 10)
));
break;
case "page0":
print statistics_display_userconfig(array(
"statistics up link" => variable_get("statistics up link", ""),
"statistics up days head" => variable_get("statistics up days head", "Today's top"),
"statistics up days top" => variable_get("statistics up days top", 0),
"statistics up alltime head" => variable_get("statistics up alltime head", 0),
"statistics up alltime top" => variable_get("statistics up alltime top", "All time top"),
"statistics up last head" => variable_get("statistics up last head", 0),
"statistics up last top" => variable_get("statistics up last top", "Last")
));
break;
case "submit statistics config":
print status(statistics_save_statistics($edit));
break;
break;
case "reset day counter":
db_query("UPDATE statistics SET daycount='0'");
variable_set("statistics timestamp", time());
break;
default:
print statistics_admin_displaycounts();
break;
}
}
}
}
/* Displays the various admin tables */
function statistics_admin_table0($dbfield, $dbrows) {
$result = db_query("SELECT statistics.nid,statistics.daycount,statistics.totalcount,statistics.timestamp,node.title FROM statistics LEFT JOIN node USING (nid) ORDER BY statistics.%s DESC LIMIT %s", $dbfield, $dbrows);
$output .= "<tr><td>". l($nid["title"], array("id" => $nid["nid"]), "node", "", array("title" => t("View this story and all of its comments."))) ."</td><td>". $nid["daycount"] ."</td><td>". $nid["totalcount"] ."</td><td>". format_date($nid["timestamp"], "small") ."</td><td><center>";
$result = db_query("SELECT nid,url,hostname,uid,timestamp FROM accesslog WHERE uid = '%s' ORDER BY timestamp DESC LIMIT %s", $id, $limit1);
}
else {
/* retrieve recent access logs for all users */
$result = db_query("SELECT nid,url,hostname,uid,MAX(timestamp) AS timestamp FROM accesslog WHERE uid != '0' GROUP BY uid ORDER BY timestamp DESC LIMIT %s", $limit1);
}
}
else if ($type == 2) {
/* retrieve recent access logs for node $id */
$result = db_query("SELECT nid,url,hostname,uid,timestamp FROM accesslog WHERE nid = '%s' ORDER BY timestamp DESC LIMIT %s", $id, $limit1);
}
else if ($type == 3) {
/* retrieve recent access logs for hostname $id */
$result = db_query("SELECT nid,url,hostname,uid,timestamp FROM accesslog WHERE hostname = '%s' ORDER BY timestamp DESC LIMIT %s", $id, $limit1);
}
else {
/* retrieve all recent access logs */
$result = db_query("SELECT nid,url,hostname,uid,timestamp FROM accesslog ORDER BY timestamp DESC LIMIT %s", $limit0);
$query = "SELECT url,timestamp FROM accesslog WHERE nid='$nid' AND url != '' ORDER BY timestamp DESC LIMIT 15";
}
elseif ($view == "internal") {
$query = "SELECT url,timestamp FROM accesslog WHERE nid='$nid' AND url LIKE '%". check_input($HTTP_HOST) ."%' ORDER BY timestamp DESC LIMIT 15";
$describe = "internal ";
}
else {
/* default to external referrers */
$query = "SELECT url,timestamp FROM accesslog WHERE nid='$nid' AND url NOT LIKE '%". check_input($HTTP_HOST) ."%' AND url != '' ORDER BY timestamp DESC LIMIT 15";
$describe = "external ";
}
$result = db_query($query);
$output = "<h3>Most recent ". $describe ."referrers for node \"". l($node->title, array("id" => "$nid"), "node", "", array("title" => t("View this story and all of its comments."))) ."\"</h3>";
}
else {
if ($view == "all") {
$query = "SELECT url,timestamp FROM accesslog WHERE url != '' ORDER BY timestamp DESC LIMIT 15";
}
elseif ($view == "internal") {
$query = "SELECT url,timestamp FROM accesslog WHERE url LIKE '%". check_input($HTTP_HOST) ."%' ORDER BY timestamp DESC LIMIT 15";
$describe = "internal ";
}
else {
$query = "SELECT url,timestamp FROM accesslog WHERE url NOT LIKE '%". check_input($HTTP_HOST) ."%' AND url != '' ORDER BY timestamp DESC LIMIT 15";
$query = "SELECT url, COUNT(url) AS count FROM accesslog WHERE nid='$nid' AND url != '' GROUP BY url ORDER BY count DESC";
}
elseif ($view == "internal") {
$query = "SELECT url, COUNT(url) AS count FROM accesslog WHERE nid='$nid' AND url LIKE '%". check_input($HTTP_HOST) ."%' GROUP BY url ORDER BY count DESC";
$describe = "internal ";
}
else {
/* default to external */
$query = "SELECT url, COUNT(url) AS count FROM accesslog WHERE nid='$nid' AND url NOT LIKE '%". check_input($HTTP_HOST) ."%' AND url != '' GROUP BY url ORDER BY count DESC";
$describe = "external ";
}
$output = "<h3>Top ". $describe ."referrers of the past ". format_interval(variable_get("stats flush log", 259200)) ." for node \"". l($node->title, array("id" => "$nid"), "node", "", array("title" => t("View this story and all of its comments."))) ."\"</h3>";
}
else {
if ($view == "all") {
$query = "SELECT url, COUNT(url) AS count FROM accesslog WHERE url != '' GROUP BY url ORDER BY count DESC";
}
elseif ($view == "internal") {
$query = "SELECT url, COUNT(url) AS count FROM accesslog WHERE url LIKE '%". check_input($HTTP_HOST) ."%' GROUP BY url ORDER BY count DESC";
$describe = "internal ";
}
else {
/* default to external */
$query = "SELECT url, COUNT(url) AS count FROM accesslog WHERE url NOT LIKE '%". check_input($HTTP_HOST) ."%' AND url != '' GROUP BY url ORDER BY count DESC";
$describe = "external ";
}
$output = "<h3>Top ". $describe ."referrers of the past ". format_interval(variable_get("stats flush log", 259200)) ."</h3>";
$form = form_textfield(t("Block name"), "stats b0 title0", $edit["stats b0 title0"], 20, 40, "This module generates a block with top nodes. You may assign a name for this block.");
$form .= form_textfield(t("Today's top nodes title"), "stats b0 days head", $edit["stats b0 days head"], 20, 40, "Specify a name for the \"day's top\" section of the block generated by this module. (HTML tags permitted)");
$form .= form_select(t("Number of day's top views to display"), "stats b0 days top", $edit["stats b0 days top"], array("0" => t("disabled"), "1" => "1", "2" => "2", "3" => "3", "4" => "4", "5" => "5", "6" => "6", "7" => "7", "8" => "8", "9" => "9", "10" => "10", "15" => "15", "20" => "20", "25" => "25", "30" => "30", "40" => "40"), "Set how many \"today's top\" nodes to display on the block generated by this module.");
$form .= "<hr />";
$form .= form_textfield(t("All time top nodes title"), "stats b0 alltime head", $edit["stats b0 alltime head"], 20, 40, "Specify a name for the \"all time top\" section of the block generated by this module. (HTML tags permitted)");
$form .= form_select(t("Number of all time views to display"), "stats b0 alltime top", $edit["stats b0 alltime top"], array("0" => t("disabled"), "1" => "1", "2" => "2", "3" => "3", "4" => "4", "5" => "5", "6" => "6", "7" => "7", "8" => "8", "9" => "9", "10" => "10", "15" => "15", "20" => "20", "25" => "25", "30" => "30", "40" => "40"), "Set how many \"all time top\" nodes to display on the block generated by this module.");
$form .= "<hr>";
$form .= form_textfield(t("Most recent views heading"), "stats b0 last head", $edit["stats b0 last head"], 20, 40, "Specify a name for the \"last views\" section of the block generated by this module. (HTML tags permitted)");
$form .= form_select(t("Number of most recent views to display"), "stats b0 last top", $edit["stats b0 last top"], array("0" => t("disabled"), "1" => "1", "2" => "2", "3" => "3", "4" => "4", "5" => "5", "6" => "6", "7" => "7", "8" => "8", "9" => "9", "10" => "10", "15" => "15", "20" => "20", "25" => "25", "30" => "30", "40" => "40"), "Set how many \"last viewed\" nodes to display on the block generated by this module.");
/* Displays the block configuration administration form */
function statistics_config_block1($edit) {
$form .= form_textfield(t("Block name"), "stats b1 title0", $edit["stats b1 title0"], 20, 40, "This module generates a block displaying how many users/guests are online. You may assign a name for this block.");
$form .= form_textfield(t("Sub-block name"), "stats b1 title1", $edit["stats b1 title1"], 20, 40, "This module generates a sub-block listing the names of currently online users. You may assign a name for this block.");
$form .= form_select(t("Activity trheshold"), "stats b1 time", $edit["stats b1 time"], $period, "How long ago a user (or guest) must have been active to be considered online.");
$form .= form_select(t("Maximum characters of user's name to display"), "stats b1 maxname len", $edit["stats b1 maxname len"], array("1" => "1", "5" => "5", "10" => "10", "15" => "15", "20" => "20", "25" => "25", "30" => "30", "35" => "35", "40" => "40", "45" => "45", "50" => "50", "55" => "55", "60" => "60"), "What is the maximum characters of a user's name to to display in the sub-block.");
$form .= form_select(t("How many online users to list"), "stats b1 max names", $edit["stats b1 max names"], array("0" => "0", "1" => "1", "2" => "2", "3" => "3", "4" => "4", "5" => "5", "6" => "6", "7" => "7", "8" => "8", "9" => "9", "10" => "10", "15" => "15", "20" => "20", "50" => "50", "100" => "100"), "How many online user's names to display in the sub-block.");
/* Displays the user page configuration administration form */
function statistics_display_userconfig($edit) {
$form = form_textfield(t("Name for link to user page"), "statistics up link", $edit["statistics up link"], 20, 40, "This node generates a user page with top nodes. If you wish a link added automatically, specify a name.");
$form .= "<hr />";
$form .= form_textfield(t("Today's top nodes title"), "statistics up days head", $edit["statistics up days head"], 20, 40, "Specify a name for the \"day's top\" section of the user page generated by this module.");
$form .= form_select(t("Number of nodes to display for \"day's top\""), "statistics up days top", $edit["statistics up days top"], array("0" => t("disabled"), "1" => "1", "2" => "2", "3" => "3", "4" => "4", "5" => "5", "6" => "6", "7" => "7", "8" => "8", "9" => "9", "10" => "10", "15" => "15", "20" => "20", "25" => "25"), "Set how many \"day's top\" nodes to display on the user page generated by this module.");
$form .= "<hr />";
$form .= form_textfield(t("All time top nodes title"), "statistics up alltime head", $edit["statistics up alltime head"], 20, 40, "Specify a name for the \"all time top\" section of the user page generated by this module.");
$form .= form_select(t("Number of nodes to display for \"all time\""), "statistics up alltime top", $edit["statistics up alltime top"], array("0" => t("disabled"), "1" => "1", "2" => "2", "3" => "3", "4" => "4", "5" => "5", "6" => "6", "7" => "7", "8" => "8", "9" => "9", "10" => "10", "15" => "15", "20" => "20", "25" => "25"), "Set how many \"all time top\" nodes to display on the user page generated by this module.");
$form .= "<hr />";
$form .= form_textfield(t("Last viewed nodes title"), "statistics up last head", $edit["statistics up last head"], 20, 40, "Specify a name for the \"last viewed\" section of the user page generated by this module.");
$form .= form_select(t("Number of nodes to display for \"last views\""), "statistics up last top", $edit["statistics up last top"], array("0" => t("disabled"), "1" => "1", "2" => "2", "3" => "3", "4" => "4", "5" => "5", "6" => "6", "7" => "7", "8" => "8", "9" => "9", "10" => "10", "15" => "15", "20" => "20", "25" => "25"), "Set how many \"last viewed\" nodes to display on the user page generated by this module.");
$output .= form_select(t("auto-throttle multiplier"), "stats throttle multiplier", variable_get("stats throttle multiplier", 60), $throttles, "Multiplier to define the number of page accesses made in past minute to trigger each throttle level (0-5).");
$output .= form_select(t("auto-throttle probability limiter"), "stats probability limiter", variable_get("stats probability limiter", 9), $probabilities, "Probability based efficiency mechanism. Specify the approximate % of hits that will update the throttle level. (Updates add one DB query)");
$output .= "<h4>[ node view counters: ]</h4>";
$output .= form_select(t("enable node counters"), "stats enable node counts", variable_get("stats enable node counts", 0), array("1" => t("enabled"), "0" => t("disabled")), "Increment node counter each time node is viewed.");
$output .= form_select(t("display node counters"), "statistics display status", variable_get("statistics display status", ""), array("1" => t("enabled"), "0" => t("disabled")), "Display how many times each node has been viewed. User must have 'access statistics' permissions.");
$output .= la(t("<b>reset day counter</b>"), array("mod" => "statistics", "op" => "reset day counter"));
$output .= "<br /><i>Clicking this link will reload this page without saving any other changes you've made. It will reset the day counter to now.</i>";
return $output;
}
/* Saves the values entered in the "blockconfig" administration form */
* This call gathers all the info we need on users/guests in a single
* database call, thus is quite efficient.
*/
$result = db_query("SELECT COUNT(DISTINCT hostname) AS count,uid,MAX(timestamp) as timestamp FROM accesslog WHERE timestamp >= '%s' GROUP BY uid ORDER BY timestamp DESC", (time() - $time_period));
$users = $guests = 0;
/* Count number of users & guests currently online based on db query */
while ($users_online = db_fetch_array($result)) {
if ($users_online["uid"]) {
/* Has uid, so is a registered user */
$user_list[$users] = $users_online[uid];
$users++;
}
else {
/*
* There's only going to be one return with a uid of 0, and that's the guest.
* Hence, the count of this field is the total number of guests currently online.
$result = db_query("SELECT statistics.nid,node.title FROM statistics LEFT JOIN node ON statistics.nid = node.nid ORDER BY %s DESC LIMIT %s", $dbfield, $dbrows);
while ($nid = db_fetch_array($result)) {
$output .= " - ". l($nid["title"], array("id" => $nid["nid"]), "node", "", array("title" => t("View this story and all of its comments."))) ."<br />";
}
return $output;
}
/* Function to retreive current page counter value. */
function statistics_get($nid) {
if ($nid > 0) {
/* retrieves an array with both totalcount and daycount */
$statistics = db_fetch_array(db_query("SELECT totalcount,daycount,timestamp FROM statistics WHERE nid = '%s'", $nid));
$result = db_query("SELECT statistics.nid,node.title FROM statistics LEFT JOIN node ON statistics.nid = node.nid ORDER BY %s DESC LIMIT %s", $dbfield, $dbrows);
$output .= "<tr><td><b>". l($nid["title"], array("id" => $nid["nid"]), "node", "", array("title" => t("View this story and all of its comments."))) ."</b></td><td align=\"right\"><small>". t("Submitted by %a on %b", array("%a" => format_name($content), "%b" => format_date($content->created, "large"))) ."</td></tr>";
