NAME

Apache::Scoreboard - Perl interface to the Apache scoreboard structure

SYNOPSIS

  use Apache::Scoreboard ();

  #inside httpd
  my $image = Apache::Scoreboard->image;

  #outside httpd
  my $image = Apache::Scoreboard->fetch("http://localhost/scoreboard");

DESCRIPTION

Apache keeps track of server activity in a structure known as the scoreboard. There is a slot in the scoreboard for each child server, containing information such as status, access count, bytes served and cpu time. This same information is used by mod_status to provide current server statistics in a human readable form.

METHODS

image

This method returns an object for accessing the scoreboard structure when running inside the server:

  my $image = Apache::Scoreboard->image;

fetch

This method fetches the scoreboard structure from a remote server, which must contain the following configuration:

 PerlModule Apache::Scoreboard
 <Location /scoreboard>
    SetHandler perl-script
    PerlHandler Apache::Scoreboard::send
    order deny,allow
    deny from all
    #same config you have for mod_status
    allow from 127.0.0.1 ...
 </Location>

If the remote server is not configured to use mod_perl or simply for a smaller footprint, see the apxs directory for mod_scoreboard_send:

 LoadModule scoreboard_send_module libexec/mod_scoreboard_send.so

 <Location /scoreboard>
    SetHandler scoreboard-send-handler
    order deny,allow
    deny from all
    allow from 127.0.0.1 ...
 </Location>

The image can then be fetched via http:

  my $image = Apache::Scoreboard->fetch("http://remote-hostname/scoreboard");

fetch_store

retrieve

The fetch_store method is used to fetch the image once from and remote server and save it to disk. The image can then be read by other processes with the retrieve function. This way, multiple processes can access a remote scoreboard with just a single request to the remote server. Example:

 Apache::Scoreboard->fetch_store($url, $local_filename);

 my $image = Apache::Scoreboard->retrieve($local_filename);

parent

This method returns a reference to the first parent score entry in the list, blessed into the Apache::ParentScore class:

 my $parent = $image->parent;

Iterating over the list of scoreboard slots is done like so:

 for (my $parent = $image->parent; $parent; $parent = $parent->next) {
     my $pid = $parent->pid; #pid of the child

     my $server = $parent->server; #Apache::ServerScore object

     ...
 }

pids

Returns an array reference of all child pids:

 my $pids = $image->pids;

The Apache::ParentScore Class

pid

The parent keeps track of child pids with this field:

 my $pid = $parent->pid;

server

Returns a reference to the corresponding Apache::ServerScore structure:

 my $server = $parent->server;

next

Returns a reference to the next Apache::ParentScore object in the list:

 my $p = $parent->next;

The Apache::ServerScore Class

status

This method returns the status of child server, which is one of:

 "_" Waiting for Connection
 "S" Starting up
 "R" Reading Request
 "W" Sending Reply
 "K" Keepalive (read)
 "D" DNS Lookup
 "L" Logging
 "G" Gracefully finishing
 "." Open slot with no current process

access_count

The access count of the child server:

 my $count = $server->access_count;

request

The first 64 characters of the HTTP request:

 #e.g.: GET /scoreboard HTTP/1.0
 my $request = $server->request;

client

The ip address or hostname of the client:

 #e.g.: 127.0.0.1
 my $client = $server->client;

bytes_served

Total number of bytes served by this child:

 my $bytes = $server->bytes_served;

conn_bytes

Number of bytes served by the last connection in this child:

 my $bytes = $server->conn_bytes;

conn_count

Number of requests served by the last connection in this child:

 my $count = $server->conn_count;

times

In a list context, returns a four-element list giving the user and system times, in seconds, for this process and the children of this process.

 my($user, $system, $cuser, $csystem) = $server->times;

In a scalar context, returns the overall CPU percentage for this server:

 my $cpu = $server->times;

start_time

In a list context this method returns a 2 element list with the seconds and microseconds since the epoch, when the request was started. In scalar context it returns floating seconds like Time::HiRes::time()

 my($tv_sec, $tv_usec) = $server->start_time;

 my $secs = $server->start_time;

stop_time

In a list context this method returns a 2 element list with the seconds and microseconds since the epoch, when the request was finished. In scalar context it returns floating seconds like Time::HiRes::time()

 my($tv_sec, $tv_usec) = $server->stop_time;

 my $secs = $server->stop_time;

req_time

Returns the time taken to process the request in microseconds:

 my $req_time = $server->req_time;

SEE ALSO

Apache::VMonitor(3), GTop(3)

AUTHOR

Doug MacEachern