logger.module

<?php

/**
 * @file
 * Provides event logging facilities decoupled from storage backend.
 */

/**
 * Implements hook_hook_info_alter().
 */
function logger_hook_info_alter(&$hooks) {
  // Check HOOK.form.inc files for hook_form_alter() implementations.
  $hooks['form_alter']['group'] = 'form';
}

/**
 * Logs a system event.
 *
 * Note: Backends like @link http://graphite.readthedocs.org/ Graphite @endlink
 * interpret dots (.) as path delimiters, like forward slashes (/) in a file
 * path. You need to account for this if part of your event name is dynamically
 * generated and may contain dots. For example:
 *
 * @code
 * $ip_address = str_replace('.', '_', $_SERVER['REMOTE_ADDR']);
 * logger_event(sprintf('server.remote_addr.%s', $ip_address);
 * @endcode
 *
 * @param string $name
 *   The name of the event you want to log.
 * @param string $type
 *   (Optional) The type of metric to log--one of the following values
 *   corresponding to the
 *   @link https://github.com/etsy/statsd/blob/master/docs/metric_types.md StatsD Metric Types @endlink
 *   :
 *   - count: The corresponding value is a number by which to increment (or
 *     decrement, if negative) a simple counter.
 *   - gauge: The corresponding value is a single datum, which remains constant
 *     until explicitly changed.
 *   - set: The corresponding value is a value to add to a set of unique values.
 *   - time: The corresponding value is a duration in milliseconds.
 * @param int $value
 *   (Optional) The numeric value you wish to log. Defaults to 1.
 *
 * @see hook_logger_event()
 */
function logger_event($name, $type = 'count', $value = 1) {
  // Assert valid event type.
  $valid_types = array('count', 'gauge', 'set', 'time');
  if (!in_array($type, $valid_types)) {
    $backtrace = debug_backtrace();
    if (isset($backtrace['1']['file']) && isset($backtrace['1']['line'])) {
      $message = sprintf('Invalid event type: "%s" in %s on line %s.', $type, $backtrace['1']['file'], $backtrace['1']['line']);
    }
    else {
      $message = sprintf('Invalid event type: "%s".', $type);
    }
    throw new InvalidArgumentException($message);
  }

  // Assert valid event value.
  if (!is_int($value)) {
    $backtrace = debug_backtrace();
    if (isset($backtrace['1']['file']) && isset($backtrace['1']['line'])) {
      $message = sprintf('Invalid event value: "%s" in %s on line %s.', $value, $backtrace['1']['file'], $backtrace['1']['line']);
    }
    else {
      $message = sprintf('Invalid event value: "%s".', $value);
    }
    throw new InvalidArgumentException($message);
  }

  // Conditionally log events to watchdog for debugging purposes.
  if (variable_get('logger_debug', FALSE)) {
    watchdog('logger', 'Logger Event: @name | @type | @value', array(
      '@name' => $name,
      '@type' => $type,
      '@value' => $value,
    ), WATCHDOG_DEBUG);
  }

  module_invoke_all('logger_event', $name, $type, $value);
}

/**
 * Logs the start of a process with the given name.
 *
 * @param string $name
 *   The 'process_name' component used in the logger event name.
 * @param string $group
 *   (Optional) The 'group' component used in the logger event name. Defaults to
 *   'logger'.
 */
function logger_process_start($name, $group = 'logger') {
  // Cleanup existing timers with the same name to prevent accumulation.
  $timer_name = _logger_process_timer_name($name);
  _logger_timer_destroy($timer_name);
  logger_event("processes.{$group}.{$name}.invoked");
  timer_start($timer_name);
}

/**
 * Logs the end of a process with the given name.
 *
 * @param string $name
 *   The 'process_name' component used in the logger event name.
 * @param string $group
 *   (Optional) The 'group' component used in the logger event name. Defaults to
 *   'logger'.
 * @param string $status
 *   (Optional) The 'status' component used in the logger event name. Defaults
 *   to 'ok'.
 */
function logger_process_end($name, $group = 'logger', $status = 'ok') {
  $timer_name = _logger_process_timer_name($name);
  timer_stop($timer_name);
  logger_event("processes.{$group}.{$name}.time_to_complete", 'time', (int) timer_read($timer_name));
  logger_event("processes.{$group}.{$name}.completed");
  logger_event("processes.{$group}.{$name}.statuses.{$status}");
  _logger_timer_destroy($timer_name);
}

/**
 * Formats a timer name.
 *
 * @param string $process_name
 *   The name of the process to use in naming the timer.
 *
 * @return string
 *   The formatted timer name.
 */
function _logger_process_timer_name($process_name) {
  return "logger_process_timer_{$process_name}";
}

/**
 * Unsets the variable for a given timer.
 *
 * @param string $timer_name
 *   The name of the timer to destroy.
 */
function _logger_timer_destroy($timer_name) {
  unset($GLOBALS['timers'][$timer_name]);
}