Skip to content

Latest commit

 

History

History
297 lines (249 loc) · 8.6 KB

README.md

File metadata and controls

297 lines (249 loc) · 8.6 KB
Raw

Log

Here you can find help on how to log information in TAO.

Advanced Logger

The advanced logger implements PSR-3 and is useful to add extra log information, such as:

  • User data.
  • Exception trace.
  • Request data, i.e: endpoint, arguments, server ip, etc.
  • ...and unlimited number of custom context extenders by composition.

Implementation:

IMPORTANT: The AdvancedLogger is already available from the DI Container.

Example:

It will log the exception details based on custom context parameters.

use oat\oatbox\log\logger\AdvancedLogger;
use \oat\oatbox\log\logger\extender\ContextExtenderInterface;

$someExceptionCaught = new Exception(
    'Error 2',
    2,
    new Exception(
        'Error 1',
        1
    )
);

/** 
 * You can also add extra context information for your logs by providing context extenders.
 * 
 * @var ContextExtenderInterface $extraContextExtender
 * @var AdvancedLogger $logger 
 */
$logger->addContextExtender($extraContextExtender);
$logger->critical(
    'My message',
    [
        ContextExtenderInterface::CONTEXT_EXCEPTION => $someExceptionCaught
    ]
);

The log result will be something like this:

[2021-11-24 09:12:11] NULL.CRITICAL: My message {
    "contextException":"[object] (Exception(code: 2): Error 2 at /var/www/html/index.php:36, Exception(code: 1): Error 1 at /var/www/html/index.php:39)",
    "contextRequestData":{"serverIp":"172.18.0.3","serverName":"tao.localhost","requestUri":"/taoItems/Items/index","requestMethod":"GET"},
    "contextUserData":{"id":"https://test-tao-deploy.docker.localhost/ontologies/tao.rdf#superUser"}
}

Logger

Tao platform logger is set in config generis/log.conf.php. It accepts a Psr3 logger interface.

To make life easier a wrapper exists to send log through monolog.

1. Propagation

The logger is passed to object in platform bootstrapping. It means that ConfigurableService, Action and Controller using LoggerAwareInterface will receive the logger. It can be accessed also via ServiceManager with key generis/log

2. Log Level

To implements different strategy, developers must use logger following log level described by RFC 5424.

 - **DEBUG** (100): Detailed debug information.
 
 - **INFO** (200): Interesting events. Examples: User logs in, SQL logs.
 
 - **NOTICE** (250): Normal but significant events.
 
 - **WARNING** (300): Exceptional occurrences that are not errors. Examples:
   Use of deprecated APIs, poor use of an API, undesirable things that are not
   necessarily wrong.
 
 - **ERROR** (400): Runtime errors that do not require immediate action but
   should typically be logged and monitored.
 
 - **CRITICAL** (500): Critical conditions. Example: Application component
   unavailable, unexpected exception.
 
 - **ALERT** (550): Action must be taken immediately. Example: Entire website
   down, database unavailable, etc. This should trigger the SMS alerts and wake
   you up.
 
 - **EMERGENCY** (600): Emergency: system is unusable.

The LoggerAwareTrait provides wrapper methods, see \Psr\Log\LoggerTrait

3. Tao Monolog

To send log to monolog a wrapper exists: TaoMonolog. It is a configurable service in charge to build the monolog logger from a config.

Example of generis/log config:

return new oat\oatbox\log\LoggerService(array(
       'logger' => array(
           'class' => 'oat\\oatbox\\log\\logger\\TaoMonolog',
           'options' => array(
               'name' => 'tao',
               'handlers' => array(
                   array(
                       'class' => 'Monolog\\Handler\\StreamHandler',
                       'options' => array(
                           '/var/www/tao/package-tao/test-log.log',
                           100
                       )
                   ),
               )
           )
       )
   ));

To have a better view of monolog possibility, please check:

4. Backward compatibility

To ensure backward compatibility common_Logger wrap all cal to logger service. common_Logger is now deprecated.

To keep logger backward compatibility a TaoLog logger can use old parameter format:

return new oat\oatbox\log\LoggerService(array(
    'logger' => array(
        'class' => 'oat\\oatbox\\log\\logger\\TaoMonolog',
        'options' => array(
            'appenders' => array(
                //Example of a UDP Appender
                array(
                    'class' => 'UDPAppender',
                    'host' => '127.0.0.1',
                    'port' => 5775,
                    'threshold' => 1,
                    'prefix' => 'tao'
                ),
            )
        )
    ))
));

3. Using setup.json

To use TaoMonolog:

{
  "generis": {
    "log" : {
      "type": "configurableService",
      "class":"oat\\oatbox\\log\\LoggerService",
      "options": {
        "logger": {
		  "class": "oat\\oatbox\\log\\logger\\TaoMonolog",
		  "options": {
			"name": "tao",
			"handlers": [
			  {
			    "class": "Monolog\\Handler\\StreamHandler",
				"options": [
                    "/var/www/tao/package-tao/test-log.log",
                    100
				]
			  },
			  {
				"class": "Monolog\\Handler\\BrowserConsoleHandler",
				"options": [
					200
				]
			  },
			  {
				"class": "Monolog\\Handler\\SlackWebhookHandler",
				"options": [
                    "https://hooks.slack.com/services/XXXXXX/XXXXXX/XXXXXX",
                    "#test",
                    "tao-bot"
                ]
              },
              {
                "class": "Monolog\\Handler\\SyslogUdpHandler",
                "options": [
                    "127.0.0.1",
                    "5775"
                ],
                "processors": [
                    {
                      "class": "oat\\oatbox\\log\\logger\\processor\\BacktraceProcessor",
                      "options": [
                        300
                      ]
                    },
                    {
                      "class": "Monolog\\Processor\\MemoryUsageProcessor"
                    },
                    {
                       "class": "Monolog\\Processor\\MemoryPeakUsageProcessor"
                    }
                ]
              }
            ],
            "processors": [
                {
                    "class": "Monolog\\Processor\\PsrLogMessageProcessor"
                },
                {
                    "class": "Monolog\\Processor\\UidProcessor",
                    "options": [
                      24
                    ]
                }
            ]
        }
    }
}

To use the old format:

{
  "log": {
    "type": "configurableService",
    "class":"oat\\oatbox\\log\\LoggerService",
    "options": {
      "logger": {
        "class": "oat\\oatbox\\log\\logger\\TaoLog",
        "options": {
            "appenders": [
                {
                   "class": "UDPAppender",
                   "host": "127.0.0.1",
                   "port": 5775,
                   "threshold": 1,
                   "prefix": "offline"
                }
            ]
        }
      }
    }
  }
}

Tao Monolog Classes

Processor

BacktraceProcessor

It's adding the debug backtrace to the "extra" offset in the log record under the "trace" offset.

Parameters

  • error level (minimum error level to apply the data)
  • skip logger classes (skipping the Monolog and Tao logger classes when it's true)
  • custom class keywords to skip if the previous parameter is true
EnvironmentProcessor

It's adding the current environment details to the "extra" offset in the log record under the "stack" offset.

Parameters

  • error level (minimum error level to apply the data)

Formatter

TaoJsonLogFormatter

It's formatting the collected log record to a TAO specific json log string.

Parameters

  • error level (minimum error level to apply the data)
  • skip logger classes (skipping the Monolog and Tao logger classes when it's true)

Example

{
   "datetime":"15\/02\/2018:16:18:18 +0100",
   "severity":"ERROR",
   "content":"Hello world",
   "file":"\/var\/www\/tango\/generis\/common\/oatbox\/Configurable.php",
   "line":89,
   "stack":{
      "id":"bench-2017-0",
      "type":"tango",
      "name":"blackberry",
      "host_type":"ws"
   }
}