The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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
  }

See also: worker_score(), next_live_worker_score() and 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_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
  }

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

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.

SEE ALSO

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

AUTHOR

Doug MacEachern

Stas Bekman

Malcolm J Harwood