NAME

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

SYNOPSIS

# 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");

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 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.

The `Apache::Scoreboard` Methods

`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.

`fetch_store`

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

Fetches a remote scoreboard and stores it in the file.

see retrieve() and 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.

`parent_score`

This method returns a object of the first parent score entry in the list, blessed into the Apache::ScoreboardParentScore 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

    # 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.

`store`

Apache::Scoreboard->store($frozen_image, $store_file);

stores a frozen image on the filesystem.

`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.

The `Apache::ScoreboardParentScore` Class

To get the Apache::ScoreboardParentScore object use the $image-parent_score()|/parent_score> and $parent_score-next()|/next> methods.

`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().

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
}

`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
}

`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.

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_worker_score($worker_score)
    ) {
    # do something with $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;

The `Apache::ScoreboardWorkerScore` Methods

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`

META: complete

`my_bytes_served`

META: complete

`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;

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

`thread_num`

XXX

`tid`

XXX

`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;

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.

AUTHOR

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

The Apache::Scoreboard Methods

fetch

fetch_store

freeze

image

parent_score

pids

retrieve

send

server_limit

store

thaw

thread_limit

The Apache::ScoreboardParentScore Class

next

next_active_worker_score

next_live_worker_score

next_worker_score

pid

worker_score

The Apache::ScoreboardWorkerScore Methods

access_count

bytes_served

client

conn_bytes

conn_count

most_recent

my_access_count

my_bytes_served

request

req_time

start_time

status

stop_time

thread_num

tid

times

vhost

Outside of mod_perl Usage

SEE ALSO

AUTHOR

Module Install Instructions

The `Apache::Scoreboard` Methods

`fetch`

`fetch_store`

`freeze`

`image`

`parent_score`

`pids`

`retrieve`

`send`

`server_limit`

`store`

`thaw`

`thread_limit`

The `Apache::ScoreboardParentScore` Class

`next`

`next_active_worker_score`

`next_live_worker_score`

`next_worker_score`

`pid`

`worker_score`

The `Apache::ScoreboardWorkerScore` Methods

`access_count`

`bytes_served`

`client`

`conn_bytes`

`conn_count`

`most_recent`

`my_access_count`

`my_bytes_served`

`request`

`req_time`

`start_time`

`status`

`stop_time`

`thread_num`

`tid`

`times`

`vhost`