MCLOUD-5325: Move log section from .magento.env.yaml (magento#706)

Author: oshmyheliuk

dist/.log.env.md

@@ -0,0 +1,92 @@
+## Logging handlers
+             
+A logging handler pushes build and deploy logs to other systems. You can configure logging handlers to send messages to a remote logging server or to a messaging system like Slack or email. 
+
+### Send logs to a remote logging server
+
+You can enable a _syslog_ handler, which is ideal for logging messages related to hardware, or a Graylog Extended Log Format (GELF) handler, which is ideal for logging messages from software applications.
+
+The following example configures both of these handlers by adding the configuration to the `.magento.env.yaml` file.
+
+```yaml
+log:
+  syslog:
+    ident: "<syslog-ident>"
+    facility: 8 # http://php.net/manual/en/network.constants.php
+    min_level: "info"
+    logopts: <syslog-logopts>
+  syslog_udp:
+    host: "<syslog-host>"
+    port: <syslog-port>
+    facility: 8  # http://php.net/manual/en/network.constants.php
+    ident: "<syslog-ident>"
+    min_level: "info"
+  gelf:
+    min_level: "info"
+    use_default_formatter: true
+    additional: # Some additional information for each log message
+      project: "<some-project-id>"
+      app_id: "<some-app-id>"
+    transport:
+      http:
+        host: "<http-host>"
+        port: <http-port>
+        path: "<http-path>"
+        connection_timeout: 60
+      tcp:
+        host: "<tcp-host>"
+        port: <tcp-port>
+        connection_timeout: 60
+      udp:
+        host: "<udp-host>"
+        port: <udp-port>
+        chunk_size: 1024
+```
+### Send logs to a messaging system
+
+Optionally, you can send logs to a messaging system, such as Slack or email, to receive real-time notifications.
+
+**To configure Slack**:
+
+```yaml
+log:
+  slack:
+    token: "<your-slack-token>"
+    channel: "<your-slack-channel>"
+    username: "SlackHandler"
+    min_level: "info"
+```
+
+-  **token**— your Slack user token. Your user token authorizes Magento Commerce (Cloud) to send messages.
+-  **channel**— name of the Slack channel Magento Commerce (Cloud) sends notifications.
+-  **username**— username Magento Commerce (Cloud) uses to send notification messages in Slack.
+-  **min_level**— minimum log level for notification messages. We recommend using info.
+
+**To configure email**:
+
+```yaml
+log:
+  email:
+    to: <your-email>
+    from: <your-email>
+    subject: "Log notification from Magento Cloud"
+    min_level: "notice"
+```
+
+- **to**— email address Magento Commerce (Cloud) sends notification messages.
+- **from**— email address for sending notification messages to recipients.
+- **subject**— description of the email.
+- **min_level**— minimum log level for notification messages. We recommend using notice or warning.
+- 
+## Log levels
+
+Log levels determine the level of detail in notification messages. The following log level categories include every log level below it. For example, a `debug` level includes logging from every level, whereas an `alert` level only shows alerts and emergencies.
+
+-  **debug**—detailed debug information
+-  **info**—interesting events, such as a user login or SQL log
+-  **notice**—normal, but significant events
+-  **warning**—exceptional occurrences that are not errors, such as the use of a deprecated API or poor use of an API
+-  **error**—run-time errors that do not require immediate action
+-  **critical**—critical conditions, such as an unavailable application component or an unexpected exception
+-  **alert**—immediate action required—such as a website is down or the database is unavailable—that triggers an SMS alert
+-  **emergency**—system is unusable

dist/.magento.env.yaml

@@ -86,7 +86,8 @@ public function execute(InputInterface $input, OutputInterface $output)
 
         $this->file->filePutContents(
             $this->fileList->getEnvDistConfig(),
-            $this->formatter->format($data)
+            $this->formatter->format($data) . PHP_EOL
+            . $this->file->fileGetContents($this->fileList->getLogDistConfig())
         );
 
         $output->writeln(sprintf('Dist file was successfully generated: %s', $this->fileList->getEnvDistConfig()));

src/Command/GenerateSchema.php

@@ -47,7 +47,7 @@ public function format(array $data): string
             $magentoVersion = $item[Schema::SCHEMA_MAGENTO_VERSION] ?? '>=' . MagentoVersion::MIN_VERSION;
 
             $text .= sprintf(
-                '## %s%s%s%s',
+                '### %s%s%s%s',
                 $key,
                 self::EMPTY_LINE,
                 wordwrap($description, 120),
@@ -72,7 +72,7 @@ public function format(array $data): string
             $text .= "\n";
 
             if (!empty($item[Schema::SCHEMA_EXAMPLES])) {
-                $text .= '### Examples' . self::EMPTY_LINE;
+                $text .= 'Examples' . self::EMPTY_LINE;
 
                 foreach ($item[Schema::SCHEMA_EXAMPLES] as $example) {
                     if (!empty($example[Schema::SCHEMA_EXAMPLE_COMMENT])) {

src/Config/Schema/Formatter.php

@@ -132,6 +132,14 @@ public function getEnvDistConfig(): string
         return $this->directoryList->getMagentoRoot() . '/.magento.env.md';
     }
 
+    /**
+     * @return string
+     */
+    public function getLogDistConfig(): string
+    {
+        return $this->directoryList->getRoot() . '/dist/.log.env.md';
+    }
+
     /**
      * @return string
      */

src/Filesystem/FileList.php

@@ -39,6 +39,7 @@ public function testCron(\CliTester $I, \Codeception\Example $data): void
         $I->runDockerComposeCommand('run build cloud-build');
         $I->startEnvironment();
         $I->runDockerComposeCommand('run deploy cloud-deploy');
+        $I->runDockerComposeCommand('run deploy cloud-post-deploy');
         $I->deleteFromDatabase('cron_schedule');
         $I->runDockerComposeCommand('run deploy magento-command cron:run');
         $I->runDockerComposeCommand('run deploy magento-command cron:run');

src/Test/Functional/Acceptance/CronCest.php

@@ -77,11 +77,16 @@ public function testExecute(): void
             ->willReturn(['some' => 'schema']);
         $this->fileListMock->method('getEnvDistConfig')
             ->willReturn('.magento.env.md');
+        $this->fileListMock->method('getLogDistConfig')
+            ->willReturn('/dist/.log.env.md');
         $this->formatterMock->method('format')
             ->with(['some' => 'schema'])
             ->willReturn('some schema');
+        $this->fileMock->expects($this->once())
+            ->method('fileGetContents')
+            ->willReturn('some additional text');
         $this->fileMock->method('filePutContents')
-            ->with('.magento.env.md', 'some schema');
+            ->with('.magento.env.md', 'some schema' . PHP_EOL . 'some additional text');
 
         $this->command->execute($input, $output);
     }

src/Test/Unit/Command/GenerateSchemaTest.php

@@ -1,4 +1,4 @@
-## ENV_VARIABLE
+### ENV_VARIABLE
 
 Some description
 
@@ -8,7 +8,7 @@ Some description
 |Magento version|\>=2.1.24|
 |Stages|global|
 
-### Examples
+Examples
 
 ```yaml
   'Some example 1'

src/Test/Unit/Config/Schema/_files/.magento.env.md

@@ -125,4 +125,9 @@ public function testGetEnvDistConfig(): void
     {
         $this->assertSame('magento_root/.magento.env.md', $this->fileList->getEnvDistConfig());
     }
+
+    public function testGetLogDistConfig(): void
+    {
+        $this->assertSame('root/dist/.log.env.md', $this->fileList->getLogDistConfig());
+    }
 }