Logging Plugin Reference

This PSR compliant autoload abstract class is the core component of the ADOdb Logging Plugin. To use it, select the appropriate target method, 'builtin' or 'monolog'

 object ADOLogger(
       optional array $streamHandlers = null,
       optional string $loggingTag = 'ADODB',
       optional int $logFormat = self::LOG_FORMAT_JSON,
       optional bool debug=false
       )

use ADOdb\addins\LoggingPlugin\builtin\ADOLogger;
$loggingObject = new ADOLogger;

use ADOdb\addins\LoggingPlugin\monolog\ADOLogger;
$loggingObject = new ADOLogger;

The following items are set by default

 void log(
       int $logLevel,
       optional string $message = null
       )

This method transmits a message at the specified level. If the message is empty and the logging method is LOG_FORMAT_JSON, then the transmitted message is a JSON encoded string of values set previously using the ADOLogger::setLoggingParameter() method

use ADOdb\addins\LoggingPlugin\builtin\ADOLogger;
$loggingObject = new ADOLogger;
 
$loggingObject->log(ADOLogger::LOG_LEVEL_ALERT,'This is an alert');

 bool isLevelLogged(
       int $logLevel
       )

This method returns a boolean value indicating if stream handlers have been defined for a specific logging level. The values available match those defined in the monolog logging system.

 array getLoggedLevels()

This method returns an array of numbers that correspond to the available logging levels. The values available match those defined in the monolog logging system.

 void setConnectionObject(
       ADOConnection $connection
       )

This method pushes a previously instantiated ADOConnection object into the logging system. It is used to add additional information about the connection into a message if JSON logging is enabled, or the monolog system sends message tags. Use of the method is not required if plain text logging is used. If the method is not called, information about the instantiated ADOdb connection will not be included in the message.

bool setStreamHandlers(
  array $streamHandlers
)

This method is used to push an array of handlers into the logging class, if that was not done when the class was instantiated. If the array already exists, they are overwritten.

• If the logging method is builtin, the array is one of ADOdb StreamHandler objects.
• If the logging method is monolog, then the array is one of monolog StreamHandler objects.

Each element in the array represents a logging level, followed by the handler object for that level. If an element is not defined, it is not logged. This is how the system provides logging granularity. If the monolog logging system is used, then additional feature such as bubbling can be configured.

bool setLogFormat(
   int $logFormat
)

This method is used to change the log format.

• LOG_FORMAT_TEXT
• LOG_FORMAT_JSON

void setLoggingIdentifier (
   string $loggingIdentifier 
)

This method is used to change the logging identifier

void setLoggingParameter(
   string $key,
   mixed $value
)

This method is used to push a custom key value pair into the logging message if the message is in JSON format. If the value is in plain-text format then the pair is ignored

The value in the $value can be any JSON encodable value.

$logging = new ADGLogging;
 
$ar = array('animal'=>'pig','domesticated'=>1);
 
$logging->setLoggingParameter('zoo',$ar);

To use the logging plugin to log core product messages, the mandatory method setCoreLogging() must be executed. This attaches the logger to a global variable $ADODB_LOGGING_OBJECT. Any other custom handler that uses the $ADODB_OUTP global or the ADODB_OUTP constant will continue to work unchanged.

The $ADODB_LOGGING_OBJECT can be utilized by any external PHP script to inject messages into a logging system.

 void setCoreLogging(
     optional bool $enableBacktrace=false,
     optional bool $suppressErrorHandling=false
 )

Redirects ADOdb logging to the Logging Plugin. This provides an alternative to Debug Mode. Debug mode can also be used if required.

• If the $enableBacktrace flag is set, then additional debugging information is added to the “callStack” element in the JSON logging object
• If the $suppressErrorHandling flag is set, then the $raiseErrorFunction defined for SQL execution errors is ignored.

 bool getBacktraceStatus()

This method returns the status of backtrace transmittal as set in setCoreLogging()

 bool getErrorHandlingStatus()

This method returns the status of error suppression as set in setCoreLogging()

The following feature is only available if the monolog plugin is used.

void setMessageTags(
  optional bool $switchOnTag=true,
  optional bool $addSystemTags=false
)

This method activates/deactivates the inclusion of message tags onto the end of each message. If the $addSystemTags flag is set, then a set of pre-formatted JSON tags are included as well.

  void setMessageTag(
    string $key,
    optional mixed $value=null
    )

This method pushes a key → value pair into the tags section of the message. if the $addSystemTags value is true, the pair is appended to the default system tags set.

$loggingObject->setMessageTag('application','production');

 void pushProcessor(
    string $processorName
 )

This feature allows use to append the output of one of Monologs Processors to the log message. If this feature is used. then it overrides the standard tagging feature described above.

use ADOdb\addins\LoggingPlugin\monolog\ADOLogger;
$loggingObject = new ADOLogger;
 
$loggingObject->pushProcessor('MemoryUsageProcessor');

Appends the following tag to the end of the log message instead of the default tag set

 {"memory_usage":"4 MB"}