CS346 - Spring 2011
Database System Implementation

A General Statistics Tracker for RedBase
You may find it useful to track certain statistics as your RedBase system executes. For example, you may want to know what percentage of page requests were found in the buffer pool, or how many times a particular file was flushed to disk. Later on you may want to track statistics about index behavior or query processing. We are providing a general statistics package for your use, encapsulated in the StatisticsMgr class described below.

Statistics are collected and reported only if flag -DPF_STATS is included during compilation. We have already set up statistics reporting within the buffer manager of the PF component. We track the total number of read-page and write-page requests that the buffer manager issues to the file system. In addition to buffer I/O statistics, we track the total number of page requests sent to the buffer manager, along with the number of pages found in the buffer versus those that needed to be be fetched from disk. A complete list of the PF statistics keys (more on this below) can be found in the file pf_statistics.h.

StatisticsMgr Class

The StatisticsMgr class enables dynamic tracking of statistics. Each statistic to be tracked is identified by a key, which is a distinct character string such as "WRITEPAGE". Every key that has been registered with the statistics manager has an integer value associated with it, representing the current value of that statistic (such as the number of pages written to disk so far).

If you want to use the statistics package, your program should create one instance of the StatisticsMgr class, with all requests to track statistics being directed to that one instance. Below, the public methods of the class declaration are shown first, followed by descriptions of the methods. As usual, the first two methods in the class declaration are the constructor and destructor methods and are not explained further. Nonzero return codes are discussed within the method descriptions.

For an example of how we used the statistics package in our tests of the PF component, see pf_test2.cc. 

class StatisticsMgr { 
  public: 
    StatisticsMgr  ();                       // Constructor 
    ~StatisticsMgr ();                       // Destructor

    // Register a new statistic or track a change to an existing one
    RC Register    (const char * const psKey, 
                    const Stat_Operation op,
                    const int * const piValue = NULL);   

    // Get value for a statistic.  Caller must delete returned object.
    int* Get       (const char *psKey);      

    RC Print       (const char *psKey);      // Print value for a statistic
    void Print     ();                       // Print all statistics values
    RC Reset       (const char *psKey);      // Reset value of a statistic
    void Reset     ();                       // Reset all of the statistics
 };

RC Register (const char * const psKey, const Stat_Operation op, const int * const piValue = NULL)

This is the controlling method for the statistics package. This method is called to track changes to an existing statistic, or to create a new statistic to track. psKey is an identifier (or key) for one statistic. op is a Stat_Operation indicating what operation to perform on the statistic. Valid values for Stat_Operation are: If psKey is an identifier not yet associated with a statistic, then a new statistic is added to the statistics manager with an initial value of 0. The operation op is then performed as indicated above. A return code of 0 indicates success, while the positive return code STAT_INVALID_ARGS indicates invalid arguments in the method call.

int* Get (const char *psKey)

This method returns a pointer to a copy of the current value of the statistic named psKey. If no statistic with that name exists then NULL is returned. The caller is responsible for deleting the memory returned by this method.

RC Print (const char *psKey)
void Print ()

These are simple methods that write the name of a statistic followed by its current value to the Unix stderr output stream. If psKey is included then only that statistic is printed; otherwise all statistics are printed. When psKey is included the possible return codes are: 0 for success, STAT_INVALID_ARGS when psKey is NULL, or STAT_UNKNOWN_KEY when psKey is not a statistic known to the system.

RC Reset (const char *psKey)
void Reset ()

These methods reset the values of one or all statistics to 0. When psKey is included (to reset only one statistic) the possible return codes are: 0 for success, STAT_INVALID_ARGS when psKey is NULL, or STAT_UNKNOWN_KEY when psKey is not a statistic known to the system.