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.

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.

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

Fetches a remote scoreboard and stores it in the file.

see retrieve() and store().

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

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.

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

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)

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

  Apache::Scoreboard::send();

a response handler which sends the scoreboard image. See fetch() for details.

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::Scoreboard->store($frozen_image, $store_file);

stores a frozen image on the filesystem.

  my $thawed_image = Apache::Scoreboard->thaw($pool, $frozen_image);

thaws a frozen image, turning it into the Apache::Scoreboard object.

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.

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

Returns the next Apache::ScoreboardParentScore object in the list of parent scores (servers):

  my $parent_score_next = $parent_score->next;

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

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

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

Returns the pid of the parent score (server):

  my $pid = $parent_score->pid;

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

The access count of the worker:

  my $count = $worker_score->access_count;

Total number of bytes served by this child:

  my $bytes = $worker_score->bytes_served;

The ip address or hostname of the client:

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

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

  my $bytes = $worker_score->conn_bytes;

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

  my $count = $worker_score->conn_count;

META: complete

META: complete

META: complete

The first 64 characters of the HTTP request:

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

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.

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

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)

XXX

XXX

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;

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::VMonitor(3), GTop(3)

Doug MacEachern

Stas Bekman

Malcolm J Harwood