Apache::Scoreboard - Perl interface to the Apache scoreboard structure
# Configuration in httpd.conf: # mod_status should be compiled in (it is by default) ExtendedStatus On # in your perl code: use Apache::Scoreboard (); #inside httpd my $image = Apache::Scoreboard->image; #outside httpd my $image = Apache::Scoreboard->fetch("http://localhost/scoreboard");
Apache keeps track of server activity in a structure known as the scoreboard. There is a slot in the scoreboard for each child server and its workers (be it threads or processes), containing information such as status, access count, bytes served and cpu time, and much more. This same information is used by mod_status to provide current server statistics in a human readable form. Apache::Scoreboard provides the Perl API to access the scoreboard. Apache::VMonitor is an extended equivalent of mod_status written in Perl.
scoreboard
mod_status
Apache::Scoreboard
Apache::VMonitor
fetch
This method fetches the Apache::Scoreboard object 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 the C module mod_scoreboard_send, which once built (like any other Apache module) can be configured as following:
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");
Note that if the the code processing the scoreboard running under the same server, you should be using the image() method, which retrieves the scoreboard directly from the server memory.
image()
fetch_store
Apache::Scoreboard->fetch_store($retrieve_url, $local_filename);
Fetches a remote scoreboard and stores it in the file.
see retrieve() and store().
retrieve()
store()
freeze
my $image = Apache::Scoreboard->fetch($pool, $retrieve_url);
Freeze the image so it can be later restored and used. The frozen image for example can be stored on the filesystem and then read in:
my $image = Apache::Scoreboard->fetch($pool, $retrieve_url); my $frozen_image = $image->freeze; Apache::Scoreboard->store($frozen_image, $store_file);
See store().
image
This method returns an object for accessing the scoreboard structure when running inside the server:
my $image = Apache::Scoreboard->image;
If you want to fetch a scoreboard from a different server, or if the code runs outside the mod_perl server use the fetch() or the fetch_store() methods.
fetch()
fetch_store()
parent_score
This method returns a object of the first parent score entry in the list, blessed into the Apache::ScoreboardParentScore class:
Apache::ScoreboardParentScore
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 # Apache::ScoreboardWorkerScore object my $wscore = $parent_score->worker_score; ... }
pids
Returns an reference to an array containing all child pids:
my $pids = $image->pids;
META: check whether we get them all (if there is a hole due to a proc in the middle of the list that was killed)
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($retrieve_url, $local_filename); my $image = Apache::Scoreboard->retrieve($local_filename);
send
Apache::Scoreboard::send();
a response handler which sends the scoreboard image. See fetch() for details.
server_limit
Returns a server limit for the given Apache server.
my $server_limit = $image->server_limit;
use this instead of the deprecated Apache::Const::SERVER_LIMIT constant.
Apache::Const::SERVER_LIMIT
store
Apache::Scoreboard->store($frozen_image, $store_file);
stores a frozen image on the filesystem.
frozen
thaw
my $thawed_image = Apache::Scoreboard->thaw($pool, $frozen_image);
thaws a frozen image, turning it into the Apache::Scoreboard object.
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.
Apache::Const::THREAD_LIMIT
To get the Apache::ScoreboardParentScore object use the $image-parent_score()|/parent_score> and $parent_score-next()|/next> methods.
$image-parent_score()|/parent_score
$parent_score-next()|/next
next
Returns the next Apache::ScoreboardParentScore object in the list of parent scores (servers):
my $parent_score_next = $parent_score->next;
next_active_worker_score
my $worker_score_next = $parent_score->next_active_worker_score($worker_score)
Returns the next active Apache::ScoreboardWorkerScore object of the given parent score. An active worker is defined as a worker that does something at the moment this method was called (for the live image) or if it did something when the snapshot of the scoreboard was taken (via send() or freeze().
Apache::ScoreboardWorkerScore
send()
freeze()
This is how to traverse all active workers for the given parent score:
for (my $worker_score = $parent_score->worker_score; $worker_score; $worker_score = $parent_score->next_active_worker_score($worker_score) ) { # do something with $worker_score }
See also: worker_score(), next_live_worker_score() and next_worker_score().
worker_score()
next_live_worker_score()
next_worker_score()
next_live_worker_score
my $worker_score_next = $parent_score->next_live_worker_score($worker_score)
Returns the next live Apache::ScoreboardWorkerScore object of the given parent score. The live worker is defined as a worker that have served/serves at least one request and isn't yet dead.
This is how to traverse all workers for the given parent score:
for (my $worker_score = $parent_score->worker_score; $worker_score; $worker_score = $parent_score->next_live_worker_score($worker_score) ) { # do something with $worker_score }
See also: worker_score(), next_active_worker_score() and next_worker_score().
next_active_worker_score()
next_worker_score
my $worker_score_next = $parent_score->next_worker_score($worker_score)
Returns the next Apache::ScoreboardWorkerScore object of the given parent score.
for (my $worker_score = $parent_score->worker_score; $worker_score; $worker_score = $parent_score->next_worker_score($worker_score) ) { # do something with $worker_score }
See also: worker_score(), next_active_worker_score() and next_live_worker_score().
pid
Returns the pid of the parent score (server):
my $pid = $parent_score->pid;
worker_score
Returns the first Apache::ScoreboardWorkerScore object of the given parent score:
my $worker_score = $parent_score->worker_score;
See also: next_active_worker_score(), next_live_worker_score() and next_worker_score().
To get the Apache::ScoreboardWorkerScore object use the following methods: worker_score(), next_active_worker_score(), next_live_worker_score() and next_worker_score().
access_count
The access count of the worker:
my $count = $worker_score->access_count;
bytes_served
Total number of bytes served by this child:
my $bytes = $worker_score->bytes_served;
client
The ip address or hostname of the client:
#e.g.: 127.0.0.1 my $client = $worker_score->client;
conn_bytes
Number of bytes served by the last connection in this child:
my $bytes = $worker_score->conn_bytes;
conn_count
Number of requests served by the last connection in this child:
my $count = $worker_score->conn_count;
most_recent
META: complete
my_access_count
my_bytes_served
request
The first 64 characters of the HTTP request:
#e.g.: GET /scoreboard HTTP/1.0 my $request = $worker_score->request;
req_time
Returns the time taken to process the request in milliseconds:
my $req_time = $worker_score->req_time;
This feature was ported in Apache 2.0.53.
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) = $worker_score->start_time; my $secs = $worker_score->start_time;
META: as of Apache 2.0.53 it's yet unavailable (needs to be ported)
status
$status = $worker_score->status();
This method returns the status of the given worker as a dual-variable. In the string context it gives a single letter, which can be mapped to the long description via the following list
"_" Waiting for Connection "S" Starting up "R" Reading Request "W" Sending Reply "K" Keepalive (read) "D" DNS Lookup "C" Closing connection "L" Logging "G" Gracefully finishing "I" Idle cleanup of worker "." Open slot with no current process
In the numerical context it returns the numerical status (which corresponds to a C define like SERVER_DEAD, SERVER_READY, etc) for which we don't really have the use at the moment. You should use the string context to get the status.
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) = $worker_score->stop_time; my $secs = $worker_score->stop_time;
thread_num
XXX
tid
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) = $worker_score->times;
In a scalar context, returns the overall CPU percentage for this worker:
my $cpu = $worker_score->times;
vhost
Returns the vhost string if there is one.
my $vhost = $worker_score->vhost;
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.
Apache::DummyScoreboard
Apache::VMonitor(3), GTop(3)
Doug MacEachern
Stas Bekman
Malcolm J Harwood
To install Apache::Scoreboard, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Apache::Scoreboard
CPAN shell
perl -MCPAN -e shell install Apache::Scoreboard
For more information on module installation, please visit the detailed CPAN module installation guide.