NAME

PApp::Log - analyze and expire the state/user databases

SYNOPSIS

use PApp::Log;

DESCRIPTION

PApp creates a new database entry for its %state hash for every new pageview. This state entry is usually between 100-4000 bytes in size, for an average of about 700-800 bytes, heavily depending on your application.

Clearly, the state database must be wiped clean from old states regularly. Similarly the user database must be cleaned up from anonymous users that didn't visit your site for a long time.

This module helps doing this, while at the same time giving you the ability to analyze the access patterns on your site/application, for example anonymizing and summarizing user behaviour to get the highly needed statistics for your customers.

There are two different tasks: logging of state/user entries (as done by log_state) und cleaning the state/user database of expired entries (done by expire_db).

expire_db also calls log_state and is usually the function you need to call.

Callbacks

During logging, the following callbacks will be called for the applications that define them:

expire_user $username, $comment

expire_state $ctime

for_user <BLOCK>;

Add a callback that is called for each user once before she is removed. The callback is called with (userid, username, comment, prefs), where prefs is a hash representing the user's preferences in PApp's internal format which will change anytime.

for_state <BLOCK>, [option => value...]

Add a callback that is called for each state (each unique page-view generates one entry in the state database). The callback is called with two hashes, the first a hash containing meta information (see below), the second is just your standard %state hash.

Contents of the meta hash:

ctime        time this page was last viewed (unix timestamp)
previd       parent state id
userid       userid in effect when that state was created
pmod         the (non-compiled) application

Additional options:

app          call only for this application
location     call only for this location
module       call only for this module

You can get a reference to the location-specific %S by using:

$S = $state->{$meta->{location}};

Examples:

Define a callback that is called for every state:

for_state {
   my ($meta, $state) = @_;
   print "STATE ",
         "APP=$meta->{pmod}{name}, ",
         "LOC=$meta->{location}, ",
         "MOD=$state->{papp_module}\n";
};

Define a callback that's only called for applications with the name "dbedit":

for_state {
   ...
} app => "dbedit";

Functions

expire_db keepuser => <seconds>, keepstate => <seconds>, keepreguser => <seconds>.

Clean the user and state databases from old states, generating log events for state and user-entries that expire but haven't been logged. This is not (yet) atomic, so do not call this function concurrently.

keepuser => <seconds> (default 60 days)
  the time after which unused anonymous users expire
keepreguser => <seconds> (default 1 year)
  the time after which even registered users expire
keepstate => <seconds> (default 14 days)
  the time after which unused state-entries expire

log_state

Run through the whole state database (not the user database) and log all state entries that have not been logged before. This is not (yet) atomic, so do not call this function concurrently.

SEE ALSO

PApp.

AUTHOR

Marc Lehmann <schmorp@schmorp.de>
http://home.schmorp.de/