Logging API

Overview

The Logging API allows you to add new entries to the Moodle log and define how they get displayed in reports. Logging is an extremely important and often neglected aspect of Moodle Plugin development. All important actions such as viewing, deleting, editing etc should be logged.

File locations

The Log API is all in lib/datalib.php and is automatically included for you during the page setup.

Functions and Examples

Following are the functions that constitute the basic log API for Moodle.

add_to_log($courseid, $module, $action, $url=, $info=, $cm=0, $user=0)
user_accesstime_log($courseid=0)
get_logs($select, array $params=null, $order='l.time DESC', $limitfrom=, $limitnum=, &$totalcount)
get_logs_usercourse($userid, $courseid, $coursestart)
get_logs_userday($userid, $courseid, $daystart)

The basic working of these functions can be categorized in two categories:-

Adding data to logs
Fetching data from logs

Let us take a deeper look into both of these:-

Adding data to Logs

In Moodle basically we have two functions that take care of adding data to the logs table:-

add_to_log($courseid, $module, $action, $url=, $info=, $cm=0, $user=0)
user_accesstime_log($courseid=0)

add_to_log()

This function is basic core function which you should use to add all your logs to the Moodle Log table. While using this function to add data to logs, please remeber that this function is more of "Action" oriented stuff rather than being based on "webserver hits", i.e the events should be logged with enough information that this data can be effectively used to regenerate the entire flow of events and action associated with any specific user. This is a simple example:-

add_to_log($course->id, 'role', 'assign', 'admin/roles/assign.php?contextid='.$context->id.'&roleid='.$roleid, $rolename, , $USER->id);

user_accesstime_log()

user_accesstime_log() is used to record the last access time for courses and site. This is basically called when a user vists the site or a course page. A simple example can be :-

$courseid = $course->id;
user_accesstime_log($courseid);

Fetching Logs

we have three functions that can take care of all your needs to interact with the existing log data in the database. Following function can be used to effectively retrieve log data as per your needs:-

get_logs($select, array $params=null, $order='l.time DESC', $limitfrom=, $limitnum=, &$totalcount)
get_logs_usercourse($userid, $courseid, $coursestart)
get_logs_userday($userid, $courseid, $daystart)

get_logs()

This is a generic function to fetch data based on a given SQL condition.

$params = array();
$selector = "l.course = :courseid";
$params['courseid'] = $course->id;
$logs = get_logs($selector, $params, $order, $limitfrom, $limitnum, $totalcount);

get_logs_usercourse()

get_logs_usercourse() returns logs data for a given specific course and user.

$coursestart = usergetmidnight($course->startdate);
$logs = get_logs_usercourse($user->id, $courseselect, $coursestart);

get_logs_userday()

This function can return logs specific to a given user and course for a given date.

$daystart = usergetmidnight(time());
$logs = get_logs_userday($user->id, $courseselect, $daystart);

Mod/*/db/log.php Files

These files specify what information should be associated with a log entry. To understand the working of these files better its necessary to understand the structure of database table 'prefix_log_display'.

Field	Type	Default	Info
id	bigint(10)	auto-incrementing	The unique ID for this comment.
module	varchar(20)		who wrote this comment
action	varchar(40)		The action associated. Ex- view, delete, update etc
mtable	varchar(30)		The name of the database table from which info will be fetched to associate with the log entry
field	varchar(200)		Which filed needs to be fetched from mtable
component	varchar(100)		The component (Frankenstyle name) associated with the entry

When a log needs to be displayed to a front end user, this table helps us determine what information needs to be displayed to the user along with the log entry, so that they can make perfect sense out of the report. Whenever we have to display a log entry for a given module and action say $module and $action, the information that's shown along with the log is the value of the 'field' column fetched from 'mtable' corresponding to the given $module and $action. Now Mod/*/db/log.php files are used to create this association by adding entries to the log_display table during the install or upgrade of a module.

Example

This a simple example of what contents of log.php files can be.

$logs = array(
   array('module'=>'page', 'action'=>'view', 'mtable'=>'page', 'field'=>'name'),
   array('module'=>'page', 'action'=>'view all', 'mtable'=>'page', 'field'=>'name'),
   array('module'=>'page', 'action'=>'update', 'mtable'=>'page', 'field'=>'name'),
   array('module'=>'page', 'action'=>'add', 'mtable'=>'page', 'field'=>'name'),
);

Documentation