PHP Log2Files Advanced Logger v 1.0

Introduction

Why

Features

• the simplicity
  
  • simple "open log with some configuration" and then "write to log"
    
  • no additional dependencies (no PEAR, no frameworks), just one PHP file with one class to include in your script
    
  • two simplicity levels:
    
    • simple mode: the textual form - doesn't need any special parsing
      
    • advanced mode: the BJSON form - stores all data with binary format which is very simple to parse and traverse. This can be used by advanced stats and monitoring tools.
  • can be used with almost anything else, easily includable into any other library, framework or existing application
    
• performance
  
  • minimal impact to the script timing,
    
  • no SQL, no databases, just PHP and filesystem,
    
  • aware of multi-threading, multiple calls from same web-client at the time, multiple scripts running at a time with very various duration (one in 10ms, while the other in 10secs),
    
  • very little thread/process switching and synchronization, allow OS caches (no flushes etc.),
    
  • so timing-cheap, that log-levels definition is not really needed (simply log all what may be needed),
    
• dedicated for production environment (megabytes of log in an hour, tens of scripts executing at a time),
  
• dedicated API for handling arrays (only values) and maps (key=>value),
  
• pre-made implementation for storage of: sessions, cookies, get&post, time of whole script execution,
  
• easy to transport storage form (copy, delete, etc.): no thousands of files,
  

How it works

• Log construction:
  Each time the new K_Log object is constructed, it receives its own unique index - which is simply the incrementing integer number.
  This number identifies particular script execution session which would generate one execution log.
  The execution log is simply a textual file (in simple mode) or binary file(in advanced mode).
  
• Logging
  Next the PHP script calls logging methods to store its log entries.
  Every call to one of logging methods adds one entry of given data (e.g. a string, a number, a key=>value pair, an array, a script timing stamp etc.).
  Each log entry is stored as a text in "simple mode" or as binary BJSON record in "advanced mode".
  
• Log compacting and clean up
  After the PHP script finishes, the execution log may have few bytes, up to few megabytes depending of size of logged data.
  To avoid having thousands of small files (which may be difficult to mantain, download, archive etc.) the execution log is merged to a bigger file called "storage file" (default size is 16MB).
  In simple mode, each execution log stored in storage file is delimeted by some pre-configured string (default is: '==*===*===*===*===*=').
  In advanced mode, each execution log is simply one BJSON array. BJSON array header contains its size in bytes, so it's extremelly easy to traverse through even very-big storage files.
  

Configuration

Config fields

• logPath [MANDATORY] - e.g. '/logs/theLog_'
  
• storagePath [OPTIONAL, default is taken from 'logPath' with suffix '_store_'] - e.g. '/logs/storedLog_'
  
• storageFileMaxSize [OPTIONAL, in bytes, default is 16MB] - e.g. 16*1024*1024 which equals to 16MB.
  Give big number here if you log "everything".
  Give small number, if you log only some small specific things.
  
• advancedMode [OPTIONAL, 0 or 1, default is 0]
  
  • If "1" each log entry is serialized in "advanced" way using BJSON (read more about "advanced mode").
    This should be used for non-trivial logs, where whole data structures may be stored and advanced parsing of log is needed (e.g. for stats).
    
  • If "0" (default) the log is written as plain text value using "entryDelimeter" after each entry (as a separator) and "logSeparator" after each executed log script.
    
  Note: advanced mode should never be mixed with simple mode in the same log file, because this will break the storage files consistency.
  
  
• startTime [OPTIONAL, default is taken from call to microtime(1)] - by setting this value, you can setup the startTime of your script different that the one generated during k_log construction.
  This may be very useful, if the K_Log instance is created a bit later than the real script start point (see examples).
  
• logPredefinedValues [OPTIONAL, 0 or 1, default is 0] - if enabled, each execution log is started with some default variables dump:
  arrays _GET, _POST, _COOKIE, _SERVER and unix timestamp are logged.
  

Config fields in simple mode

• entryDelimeter [OPTIONAL, string, default is chr(10) (linux line-break)] - the string that will be put after each log entry in "simple" mode.
  
• logSeparator [OPTIONAL, string, default is defined later] - the separator that will be used for joining logs to a "store file" in "simple" mode.
  For default this is '==*===*===*===*===*=' plus entryDelimeter.
  

Configuration examples

$log = new K_Log(array('logPath' => 'myLog'));

$log = new K_Log(
    array(
        'logPath' => 'data/logs/log',
        'storagePath' => 'data/logs/logstored_',
        'storageFileMaxSize' => 8*1024,
    ));

$log = new K_Log(
    array(
        'logPath' => 'data/logs/log',
        'storagePath' => 'data/logs/logstored_',
        'entryDelimeter' => "\r\n",
        'logSeparator' => "----\r\n"
    ));

$log = new K_Log(
    array(
        'logPath' => 'data/logs/log',
        'advancedMode' => 1
    ));

Usage

Usage examples

$log->log("simple text"); // add text entry
$log->log(1234); // add 1234 number
$log->log("1234"); // add "1234" as string
$log->logTime("executed 1st part of script"); // log the "elapsed time from execution start" in microseconds, with label "executed 1st part of script"
$log->logKeyValue("theKey", "theValue"); // log the pair of $key => $value

Demo

API Reference

new K_Log($config)

function generateFilePathForLog($idx)

function getCurrentLogFilePath()

function getWholeLog()

function log($entry)

function logArray($in)

function logMap($in)

function logAsString($entry)

function logAsInt($entry)

function logKeyValue($key, $value)

function logTime($label)

function shutdown()

Other

FAQ

Roadmap

License