Merge branch 'develop' of https://github.com/oat-sa/generis into feat…

…ure/adf-660/param-converter
oat-sa · Dec 3, 2021 · 3e473e1 · 3e473e1
2 parents 9f9b971 + 98db253
commit 3e473e1
Show file tree

Hide file tree

Showing 28 changed files with 1,612 additions and 381 deletions.
diff --git a/README.md b/README.md
@@ -7,4 +7,8 @@ Core extension, provide the low level framework and an API to manage ontologies
 
 ### Dependency Injection
 
-Read here [how to use Dependency Injection](./core/DependencyInjection/README.md)
+Read here [how to use Dependency Injection](./core/DependencyInjection/README.md).
+
+### Log
+
+Learn more here about [how to log](./common/oatbox/log/README.md).
diff --git a/common/oatbox/extension/Manifest.php b/common/oatbox/extension/Manifest.php
@@ -265,6 +265,14 @@ public function getContainerServiceProvider(): array
         return $this->manifest['containerServiceProviders'] ?? [];
     }
 
+    /**
+     * @return AbstractAction[]
+     */
+    public function getE2ePrerequisiteActions(): array
+    {
+        return $this->manifest['e2ePrerequisiteActions'] ?? [];
+    }
+
     /**
      * Extract dependencies for extensions
      * @param string $file

diff --git a/common/oatbox/log/README.md b/common/oatbox/log/README.md
@@ -0,0 +1,297 @@
+# 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:**
+
+- Check the [AdvancedLogger](./logger/AdvancedLogger.php) for more details.
+- Check the [ContextExtenderInterface](./logger/extender/ContextExtenderInterface.php) for more details.
+
+**IMPORTANT**: The AdvancedLogger is already available from the __DI Container__. 
+
+### Example:
+
+It will log the exception details based on custom `context parameters`.
+
+```php
+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:
+
+```shell
+[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](http://tools.ietf.org/html/rfc5424).
+
+     - **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:
+```php
+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:
+* generis/config/header/log.conf.php
+* https://github.com/Seldaek/monolog/blob/master/doc/02-handlers-formatters-processors.md
+
+### 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:
+```php
+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:
+```json
+{
+  "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:
+```json
+{
+  "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**
+```json
+{
+   "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"
+   }
+}
+```