===== ADOdb Logging  =====
~~NOTOC~~
<WRAP important>
This feature contains a breaking change from V5
</WRAP>

<WRAP right box center 300px>
== See Also ==
[[v6:logging:reference|Logging Plugin Reference]] \\
[[v6:logging:logging_format|Logging Formats]] \\
[[v6:logging:builtin|The Builtin Logging Plugin]] \\
[[v6:logging:monolog|The Monolog Logging Plugin]] \\
</WRAP>
==== Overview ==== 
The goal of the Logging Plugin is to provide an alternative updated logging mechanism for the core ADOdb feature, that replaces the functionality of the [[v5:userguide:debug]] feature of ADOdb. Its features include:

  * Direct integration to any stream supported by the [[https://seldaek.github.io/monolog|Monolog]] library. This library is available from [[https://packagist.org/packages/monolog/monolog|Packagist]]. 
  * Standardized syslog style file logging that separates different log levels into separate log files
  * Provision of messaging in both classic style text and JSON encoded log messages.
  * Ability to send additional tags, allowing data filtering in log management software such as Prometheus
  * Ability to log only certain levels of messages to improve usability in production environments
  * Backwards compatibility with existing ''ADOConnection::debug'' features
  * Compatible with custom error-trapping functions
  * Improved error backtrace logging

==== Concept Of Use ====
The new system works using an inverse method to the existing [[v5:userguide:debug]] flow:
  * If a logging level is defined, the logging system is always active
  * Messages are trapped and forwarded based on the logging levels that are activated.

This means that if a CRITICAL error handler is activated, then errors within ADOdb can be trapped and forwarded to a logging stream without any additional debugging information being logged. If required and configured, successful SQL Statement logging can include a debug backtrace 

==== Sample Output ====
=== Plain Text Format ===
This includes an optional additional set of custom JSON tags

''[2023-12-30T12:06:33.954984-07:00] ADODB.CRITICAL: Execution of statement failed: SELECT COUNT(*) FROM employee ,  / Error: 1146 Table 'employees.employee' doesn't exist [] {"system-type":"production"}''

=== JSON format ===

''[2023-12-30T20:26:18.567813-07:00] ADODB.CRITICAL: {"version":"1.0","ADOdbVersion":"5.23.0-dev","level":"500","shortMessage":"QUERY EXECUTION FAILURE","sqlStatement":{"sql":"SELECT COUNT(*) FROM employee","params":false},"errorCode":1146,"errorMessage":"Table 'employees.employee' doesn't exist","metaErrorCode":-18,"metaErrorMessage":"no such table","extendedData":"","host":"study","source":"cli","driver":"mysqli","php":"8.0.29","os":"WINNT"} [] {"git":{"branch":"master","commit":"ce74ea93742080211c1b7c126c80b44eb9be1277"}}''
  
This example incudes information from the Monolog [[https://github.com/Seldaek/monolog/blob/main/src/Monolog/Processor/GitProcessor.php|Git Processor]]
 
==== Prerequisites ====
  * The logging system requires a PSR style autoloader.
  * PHP must be Version 8.0 or higher
  * If the monolog plugin is used, then it must also be installed



{{tag>updated breaking}}