====== Logging module ======


===== The suggestion =====

Currently, various modules within core and contrib use various tables to store historical (i.e. "write once, read sometimes, never update") data. The most obvious is the "watchdog" table, but others exist, including "accesslog", and "zeitgeist"'s eponym table.

Logging through a unified API has the potential to reduce the code volume somehow, as all logging functions could be made one, and could also potentially be simplified to automatically record some information so that modules invoking the function don't have to write in some parameters, that could be recorded automatically.

The logging module could be used as a facade between recording modules and modules with data to record, allowing for multiples logging formats (think distributed logging, for instance, or logging to a printer for some physical audit trail situations).

  * Modules wishing to be registered as potential recorders would use a function like:
  <code php>
  global $logging_recorders = array();

  /**
   * @param string $recordee The name of the function to use the logging mechanism
   * @param string $recorder The name of the function offering to record for $recordee
   */
  function logging_register_recorder($recordee, $recorder) 
    {
    global $logging_recorders;

    $recorders[$recordee][$recorder] = 1;
    }
  </code>
  * While modules wishing to allow for logging of their call parameters could just use code like:
  <code php>
  if (function_exists('logging_record_entry')) 
    {
    logging_record_entry();
    }
  </code>
  * At this point, the logging mechanism would go through the array of recorders, check whether one or more recorders have registered for the calling function, and pass them the calling function information:
  <code php>
  fonction logging_record_entry() 
    {
    global $logging_recorders;

    $recordee = debug_backtrace[0]['function'];
    $args = debug_backtrace[0]['args'];
    if (array_key_exists($recordee, $logging_recorders))
      {
      foreach($logging_recorders[$recordee] as $recorder => $count)
        {
        if (is_callable($recorder))
          {
          $recorder($recordee, $args);
          }
        else
          die(t("In logging module, non-callable recorder %recorder was registered for recordee %recordee.",
            array('%recorder' => $recorder, '%recordee => $recordee))) ;
        }
      }
    }
  </code>
  *  Eventually recorder functions fulfill their recording contract as they wish using the original function arguments. Having the recordee name as first parameter allows the recorder function to be potentially unique for several recordees.

===== Tuning =====

An objection to this mechanism is the obvious cost of logging over situations without logging. This could be alleviated by switching the recording pairs on and off as a logging module setting. Instead of logging pairs and always invoking the recorder, the module could store a "on/off" setting for each pair, defined in admin/settings/logging. 

That way, recordee could still send recording notifications, but they would be cut off at the logging module level before reaching the recorders if the site admin thinks he doesn't need them.

===== Why bother ? =====

This came from a need initially met with the current Zeitgeist module: there is, as of Drupal 4.7RC2, no formal way to register searches being performed. Chatting on irc://irc.freenode.net/drupal confirmed that. 

The mere idea of adding code to search.module just to support zeitgeist, which is a contrib module (and not even a major one), seemed utterly illogical, although just adding _zeitgeist_store_search() within search.module/do_search() fulfilled zeitgeist's need for a clean way to grab search requests, so I didn't even suggest it.

Considering this, I suggested a hook for search recorders, that could be used by any module wishing to record search queries, and not just zeitgeist. But discussion showed this was not felt to be sufficiently general to be upheld.

I then thought on, and considered what sort of a more general contract-based mechanism could be used, that would both be extremely simple to use by recordees, so as to not affect them, and flexible enough to accomodate more general needs than just recording searches. This is the first draft of the result.