Dev.Pi.service.log - pi-engine/pi GitHub Wiki

Brief

The log service is used to record logs in the debug panel, system log or custom log file. It is very useful for developers to trace and debug codes. Its usage is:

Pi::service('log')

Relevant documentation are:

APIs

active

active($flag = null)

Enable or disable debugger.

Parameters

  • flag

Value true to enable debugger, or else disabled debugger. If the value is given, it will also decide whether to register exception handler and error handler.

default as null, you can set ip white list in configuration file to allow parts of user to view the debugger info. Or else, debugger is always enabled. Please refer to Log service config

Examples

# Use config to enable/disable debugger
Pi::service('log')->active();
# Enable debugger
Pi::service('log')->active(true);
# Disable debugger
Pi::service('log')->active(false);

mute

mute($flag = true)

Enable or disable debugger panel.

Debugger panel includes: log, debugger, profiler and dbprofiler.

  • Log panel: output info, err, warning etc during script execution.
  • Debugger panel: output variables by d() method.
  • Profiler: output execution time of block, action.
  • DBProfiler: output execution time of each sql query.

Note

Both active() and mute() methods can make the debugger panel at bottom of page visible or invisible. The different is that, active() disabled all debug behavior, mute() just hides the debugger panel, and develop can still exports log to system log or file.

Parameters

  • flag

Value true to disable debugger panel, or else enable debugger panel. Default as true.

Examples

# Use in action
public function demoAction()
{
    Pi::service('log')->mute();
    ...
}

debugger

debugger(Pi\Log\Writer\Debugger $debugger = null)

Set or get debugger instance. The debugger class is Pi\Log\Writer\Debugger.

Parameters

  • debugger

Set the debugger handler if value is not null, or else load debugger handler.

Returns

Return value is Pi\Log\Writer\Debugger instance.

Examples

// It is as same as Pi::service('log')->mute()
Pi::service('log')->debugger()->mute();

profiler

profiler(Pi\Log\Profiler $profiler = null)

Set or get profiler instance. The profiler class is Pi\Log\Profiler.

Parameters

  • profiler

Set the profiler handler if value is not null, or else load profiler handler.

Returns

Return value is Pi\Log\Profiler instance.

dbProfiler

dbProfiler(Pi\Log\DbProfiler $dbProfiler = null)

Set or get dbProfiler instance. The dbProfiler class is Pi\Log\DbProfiler.

Parameters

  • dbProfiler

Set the dbProfiler handler if value is not null, or else load dbProfiler handler.

Returns

Return value is Pi\Log\DbProfiler instance.

db

db($info)

Log DB query profiling info.

Parameters

  • info

Array include query info to log.

* message: log message
* sql: mysql query
* parameters: query parameters
* start: query execution start, format is timestamp
* elapse: execution duration
* priorityName: priority name, such as ERR, INFO, ..., if it is empty and `status` is false, ERR will be used
* status: sql execution result

Examples

// Log will appear in db panel
Pi::service('log')->db([
    'message' => '',
    'sql'     => 'select * from test',
    'start'   => time(),
    'elapse'  => 0.00123456,
    'status'  => true,
]);

start & end

start($name = 'Pi Engine')
end($name = 'Pi Engine')

These two methods use together to review the performance of a piece of codes.

Parameters

  • name

To specify which two log are a pair. And it will be posable to calculate execution duration and memory used.

Examples

// Recode performance when start
Pi::service('log')->start('test');
$result = [];
for ($i = 0; $i < 1000; $i++) {
    $result[] = $i;
}
Pi::service('log')->end('test');

In the db panel, it will export:

19:55:20.0098
test - time: 0.0002; realmem: 0; emalloc: 145024

priorityName

priorityName($priorityValue)

Get priority name if it exists.

Parameters

  • priorityValue

Priority value, type is integer. Part of them are:

* Pi\Log\Logger::EMERG
* Pi\Log\Logger::ALERT
* Pi\Log\Logger::CRIT
* For more values, please refer to Pi\Log\Logger class

Examples

Pi::service('log')->priorityName(Pi\Log\Logger::AUDIT);
// Or
Pi::service('log')->logger()->priorityName(10);

Results are:

AUDIT
null

writerPlugin

writerPlugin($name, array $options = null)

Get log writer instance.

Parameters

  • name

Writer name, it can be:

* `audit`: record logs into audit table
* `debugger`: record logs into debugger panel
* `syslog`: record logs into system log file
* `chromePhp`: record logs through chromePhp extension
* `db`: record logs into database
* `fingersCrossed`: ...
* `firePhp`: record logs into firePhp extension
* `mail`: send logs to mail
* `mongoDB`: set logs into mongoDB
* `stream`: record logs into file
* `zendMonitor`: record logs into zend platform

For information on how these writers work, please refer to Writers

  • options

Writer options, accepted options are

* filters: array of filters to add to this filter
* formatter: formatter for this writer

Examples

$options = [
    'filters' => [
        [
            'name'    => 'priority',
            'options' => [
                'priority' => Pi\Log\Logger::ALERT,
                'operator' => '>=',
            ],
        ],
    ],
];
Pi::service('log')->writerPlugin('syslog', $options);
Pi::service('log')->logger()->writerPlugin('syslog', $options);

addWriter

addWriter($writer, $priority = 1, array $options = array())

Add a writer instance into a logger. Then the Pi Engine will record logs into indicated media via these writers.

Parameters

  • writer

Writer name or writer instance. Allowed writer name are list in writerPlugin method.

  • priority

Priority to call the writer.

  • options

Writer options, accepted options are

* filters: array of filters to add to this filter
* formatter: formatter for this writer

Examples

Pi::service('log')->addWriter('audit');
Pi::service('log')->logger()->addWriter('audit');
$options = [
    'filters' => [
        [
            'name'    => 'priority',
            'options' => [
                'priority' => Pi\Log\Logger::ALERT,
                'operator' => '>=',
            ],
        ],
    ],
];
$writer = new Pi\Log\Syslog($options);
Pi::service('log')->addWriter('syslog', 2, $options);
Pi::service('log')->addWriter($writer, 2);

getWriters

getWriters()

Get all writers, documentation will come soon.

setWriters

setWriters($writers)

Set writers, documentation will come soon.

log

log($priority, $message, $extra = array())

Add a message as a log entry.

Parameters

  • priority

Logger priority.

  • message

Message to log, can be either string or array, and array data will be formatted into string.

  • extra

Extra debug data to be logged, if its value is integer, this parameter means the log time; as well as array type with time field.

* time: time of log set manually
* line: line of the debug data
* file: file of the debug data

Examples

$options = [
    'time'  => '2015-09-01 22:00:00',
    'line'  => __LINE__,
    'file'  => __FILE__,
];
Pi::service('log')->log(Pi\Log\Logger::INFO, 'test log with line and file', $options);
Pi::service('log')->logger()->log(Pi\Log\Logger::INFO, 'test log', time());

Results in debug panel are:

22:00:0014411
[info] #14 in module/demo/src/Controller/Front/TestController.php
test log with line and file
11:35:2514428
[info]
test log

emerg

emerg($message, $extra = array())

Log an EMERG message.

Parameters

  • message

Message to log, refer to message parameter of Pi\Log\Logger::log() method.

  • extra

Extra data to be logged, refer to extra parameter of Pi\Log\Logger::log() method.

Examples

$options = [
    'time'  => '2015-09-01 22:00:00',
    'line'  => __LINE__,
    'file'  => __FILE__,
];
Pi::service('log')->emerg('test log with line and file', $options);
Pi::service('log')->logger()->emerg('test log', time());

Results in debug panel:

22:00:0014411
[emerg] #14 in module/demo/src/Controller/Front/TestController.php
test log with line and file
11:44:2014428
[emerg]
test log

alert

alert($message, $extra = array())

Log an ALERT message.

Parameters

  • message

Message to log, refer to message parameter of Pi\Log\Logger::log() method.

  • extra

Extra data to be logged, refer to extra parameter of Pi\Log\Logger::log() method.

Examples

$options = [
    'time'  => strtotime('2015-09-01 22:00:00'),
    'line'  => __LINE__,
    'file'  => __FILE__,
];
Pi::service('log')->alert('test log with line and file', $options);
Pi::service('log')->logger()->alert('test log', time());

crit

crit($message, $extra = array())

Log an CRIT message.

Parameters

  • message

Message to log, refer to message parameter of Pi\Log\Logger::log() method.

  • extra

Extra data to be logged, refer to extra parameter of Pi\Log\Logger::log() method.

Examples

$options = [
    'time'  => strtotime('2015-09-01 22:00:00'),
    'line'  => __LINE__,
    'file'  => __FILE__,
];
Pi::service('log')->crit('test log with line and file', $options);
Pi::service('log')->logger()->crit('test log', time());

err

err($message, $extra = array())

Log an ERR message.

Parameters

  • message

Message to log, refer to message parameter of Pi\Log\Logger::log() method.

  • extra

Extra data to be logged, refer to extra parameter of Pi\Log\Logger::log() method.

Examples

$options = [
    'time'  => strtotime('2015-09-01 22:00:00'),
    'line'  => __LINE__,
    'file'  => __FILE__,
];
Pi::service('log')->err('test log with line and file', $options);
Pi::service('log')->logger()->err('test log', time());

warn

warn($message, $extra = array())

Log an WARNING message.

Parameters

  • message

Message to log, refer to message parameter of Pi\Log\Logger::log() method.

  • extra

Extra data to be logged, refer to extra parameter of Pi\Log\Logger::log() method.

Examples

$options = [
    'time'  => strtotime('2015-09-01 22:00:00'),
    'line'  => __LINE__,
    'file'  => __FILE__,
];
Pi::service('log')->warn('test log with line and file', $options);
Pi::service('log')->logger()->warn('test log', time());

notice

notice($message, $extra = array())

Log an NOTICE message.

Parameters

  • message

Message to log, refer to message parameter of Pi\Log\Logger::log() method.

  • extra

Extra data to be logged, refer to extra parameter of Pi\Log\Logger::log() method.

Examples

$options = [
    'time'  => strtotime('2015-09-01 22:00:00'),
    'line'  => __LINE__,
    'file'  => __FILE__,
];
Pi::service('log')->notice('test log with line and file', $options);
Pi::service('log')->logger()->notice('test log', time());

info

info($message, $extra = array())

Log an INFO message.

Parameters

  • message

Message to log, refer to message parameter of Pi\Log\Logger::log() method.

  • extra

Extra data to be logged, refer to extra parameter of Pi\Log\Logger::log() method.

Examples

$options = [
    'time'  => strtotime('2015-09-01 22:00:00'),
    'line'  => __LINE__,
    'file'  => __FILE__,
];
Pi::service('log')->info('test log with line and file', $options);
Pi::service('log')->logger()->info('test log', time());

debug

debug($message, $extra = array())

Log an DEBUG message.

Parameters

  • message

Message to log, refer to message parameter of Pi\Log\Logger::log() method.

  • extra

Extra data to be logged, refer to extra parameter of Pi\Log\Logger::log() method.

Examples

$options = [
    'time'  => strtotime('2015-09-01 22:00:00'),
    'line'  => __LINE__,
    'file'  => __FILE__,
];
Pi::service('log')->debug('test log with line and file', $options);
Pi::service('log')->logger()->debug('test log', time());

audit

audit($message, $extra = array())

Log an AUDIT message.

Parameters

  • message

Message to log, refer to message parameter of Pi\Log\Logger::log() method.

  • extra

Extra data to be logged, refer to extra parameter of Pi\Log\Logger::log() method.

Examples

$options = [
    'time'  => strtotime('2015-09-01 22:00:00'),
    'line'  => __LINE__,
    'file'  => __FILE__,
];
Pi::service('log')->audit('test log with line and file', $options);
Pi::service('log')->logger()->audit('test log', time());