/ 
Apache-Scoreboard-2.05
River stage one • 4 direct dependents • 4 total dependents
/ Apache::Scoreboard

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.

General 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 modperl
   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

see retrieve()

retrieve

The fetch_store method is used to fetch the image once from a 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_score

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

my $parent_score = $image->parent_score;

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

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

    my $server = $parent_score->server; #Apache::ServerScore object
    ...
}

pids

Returns an array reference of all child pids:

my $pids = $image->pids;

server_limit

Returns a server limit for the given image.

my $server_limit = $image->server_limit;

use this instead of the deprecated Apache::Const::SERVER_LIMIT constant.

thread_limit

Returns a threads limit per process for the given image.

my $thread_limit = $image->thread_limit;

use this instead of the deprecated Apache::Const::THREAD_LIMIT constant.

The Apache::ParentScore Class

To get the Apache::ParentScore object use the $image-parent_score()|/C_parent_score_> or $parent_score-next()|/C_next_> methods.

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

To get the Apache::ServerScore object use the $$parent-server()|/C_server_> method.

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;

META: as of Apache 2.0.53 it's yet unavailable (needs to be ported)

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;

META: as of Apache 2.0.53 it's yet unavailable (needs to be ported)

req_time

Returns the time taken to process the request in microseconds:

my $req_time = $server->req_time;

This feature was ported in Apache 2.0.53.

vhost

Returns the vhost string if there is one.

my $vhost = $server->vhost;

Outside of mod_perl Usage

Apache::DummyScoreboard is used internally if the code is not running under mod_perl. It has almost the same functionality with some limitations. See the Apache::DummyScoreboard manpage for more info.

SEE ALSO

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

AUTHOR

Doug MacEachern

Stas Bekman