Set up notifications

By default, Magento Commerce (Cloud) writes build and deploy actions to a single file called app/var/log/cloud.log, but you can also send logs to messaging systems, like Slack and email, if you want to receive real-time notifications.

For example, you may want to send a Slack message to a group of people when a deployment fails so someone can immediately start investigating what went wrong.

Plan your notifications

Before you start configuring notifications, you should spend some time thinking about the following:

  • What kind of notifications do you want to receive (Slack messages, email, both)?
  • How much detail do you want to see in the logs (see Log levels)?
  • Where do you want to set up notifications (integration, staging, production)?

For example, during initial development you may prefer email notifications that show detailed logs about your integration environment to help you debug issues before deploying to staging or production. When you’re ready to deploy to staging or production, however, you may prefer Slack messages that contain less detailed information.

The configuration file you use to set up notifications is located at the root of your project directory, so it applies to every environment you push it to. If you want to customize notifications per environment, you must modify the configuration file before pushing it to that environment.

Configure notifications

To configure notifications:

  1. Open a terminal and checkout a branch in your local environment.
  2. Locate .magento.env.yaml.sample in your project root and rename it .magento.env.yaml. The code in this file is commented out by default.
  3. Remove the code comments and add your messaging system settings, including preferred notification log level.

    For example, to configure both Slack and email configurations, use the following:

    log:
      slack:
          token: "<your-slack-token>"
          channel: "<your-slack-channel>"
          username: "SlackHandler"
          min_level: "info"
      email:
          to: <your-email>
          from: <your-email>
          subject: "Log notification from Magento Cloud"
          min_level: "notice"
    

    Magento Commerce (Cloud) only sends emails during the deployment phase.

  4. Commit and push your changes to the remote server:

     git -A && git commit -m "Configure build/deploy notifications"
     git push origin <branch-name>
    

Example Slack configuration

The following example shows a Slack-only configuration:

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 where you want Magento Commerce (Cloud) to send notifications.
  • username - Username you want Magento Commerce (Cloud) to use to send notification messages in Slack.
  • min_level - Minimum log level for notification messages. We recommend using info.

Example email configuration

The following example shows an email-only configuration:

Magento Commerce (Cloud) only sends emails during the deployment phase.

log:
  email:
      to: <your-email>
      from: <your-email>
      subject: "Log notification from Magento Cloud"
      min_level: "notice"
  • to - Email address where Magento Commerce (Cloud) will send 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 what level of detail your notification messages will contain. You can choose from the following options:

  • debug: Detailed debug information
  • info: Interesting events. For example, a user logs in, SQL logs, etc.
  • notice: Normal but significant events.
  • warning: Exceptional occurrences that are not errors. For example, use of deprecated APIs, poor use of an API, undesirable things that are not necessarily wrong.
  • error: Runtime errors that don’t require immediate action but should be logged and monitored.
  • critical: Critical conditions. For example, an unavailable application component, unexpected exceptions.
  • alert: Action must be taken immediately. For example, your website is down, the database is unavailable, etc. This should trigger SMS alerts and wake you up.
  • emergency: The system is unusable.