Install Guide
The Site-Wide Analysis Tool provides 24/7 real-time performance monitoring, reports, and recommendations to ensure the security and operability of Adobe Commerce on cloud infrastructure installations. It also provides detailed information about available and installed patches, third-party extensions, and your Adobe Commerce installation.
If you have an on-premises installation of Adobe Commerce, install an agent on your infrastructure to use the tool. You do not need to install the agent on Adobe Commerce on cloud infrastructure projects.
Agent
The Site-Wide Analysis Tool Agent allows you to use the Site-Wide Analysis Tool for on-premises installations of Adobe Commerce.
The Site-Wide Analysis Tool Agent collects application and business data, analyzes it, and provides additional insights about the health of your installation so that you can improve customer experience. It monitors your application and helps you identify performance, security, availability, and application issues.
Installing the agent requires the following steps:
-
Verify system requirements.
-
Configure API keys in the Commerce Services Connector extension.
-
Install the agent.
-
Run the agent.
System requirements
Your on-premises infrastructure must meet the following requirements before installing the agent:
-
Operating systems
- Linux x86-64 distributions, such as Red Hat® Enterprise Linux (RHEL), CentOS, Ubuntu, Debian, and similar
note important IMPORTANT Adobe Commerce is not supported on Microsoft Windows or macOS. -
Adobe Commerce 2.4.5-p1 or later (due to the dependency of Service Connector)
-
Commerce Services Connector extension
-
PHP CLI
-
Bash/shell utilities
-
php
-
wget
-
awk
-
nice
-
grep
-
openssl
-
Commerce Services Connector
The agent requires the Commerce Services Connector extension to be installed on your system and configured with API keys. To verify that the extension is installed, run the following command:
bin/magento module:status Magento_ServicesId
If you have installed the extension and configured it using an existing API key for a different service, you MUST regenerate the API key and update it in the Adobe Commerce Admin for the agent.
-
Put your website into maintenance mode.
-
Log into account.magento.com.
note note NOTE If you have trouble accessing your account, see Unable to log in to Adobe Commerce support or cloud account for troubleshooting help. -
Click API Portal.
-
Click Delete next to the existing API Key.
-
Configure a new API key.
If the extension is not installed, use the following instructions to install it:
-
Add the extension to your
composer.json
file and install it.code language-bash composer require magento/services-id
-
Enable the extension.
code language-bash bin/magento module:enable Magento_ServicesId
-
Update the database schema.
code language-bash bin/magento setup:upgrade
-
Clear the cache.
code language-bash bin/magento cache:clean
-
Configure API Keys to connect the extension to your system.
Install the agent
We have created a shell script to simplify installation. We recommend using the shell script, but you can follow the manual installation method if necessary.
Scripted
-
Download and execute the shell script.
code language-bash bash -c "$(wget -qO - https://raw.githubusercontent.com/magento-swat/install-agent-helpers/main/install.sh)"
note tip TIP We recommend installing the agent outside of your root Adobe Commerce project directory. -
Verify installation.
code language-bash ./scheduler -v
code language-bash Version: 1.0.1 Success exit.
-
After downloading and installing the agent, configure it to run using one of the following methods:
Manual manual
If you do not want to use our shell script to install the agent, then you must manually install it by following these steps:
-
Create a directory where you want to download the agent.
note tip TIP We recommend installing the agent outside of your root Adobe Commerce project directory. -
Download the binary file and unpack it.
note info INFO To use the Site-Wide Analysis Tool, you must first read and accept the Terms of Use that are presented when you access the dashboard from the Adobe Commerce Admin. For the AMD64 architecture:
-
Download the launcher archive.
code language-bash curl -O https://updater.supportinsights.adobe.com/launcher/launcher.linux-amd64.tar.gz
-
Unpack the launcher archive.
code language-bash tar -xf launcher.linux-amd64.tar.gz
For the ARM64 architecture:
-
Download the launcher archive.
code language-bash curl -O https://updater.supportinsights.adobe.com/launcher/launcher.linux-arm64.tar.gz
-
Unpack the launcher archive.
code language-bash tar -xf launcher.linux-arm64.tar.gz
-
-
(Optional) Verify the signature for the checksum file.
code language-bash echo -n "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQ0lqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FnOEFNSUlDQ2dLQ0FnRUE0M2FBTk1WRXR3eEZBdTd4TE91dQpacG5FTk9pV3Y2aXpLS29HendGRitMTzZXNEpOR3lRS1Jha0MxTXRsU283VnFPWnhUbHZSSFhQZWt6TG5vSHVHCmdmNEZKa3RPUEE2S3d6cjF4WFZ3RVg4MEFYU1JNYTFadzdyOThhenh0ZHdURVh3bU9GUXdDcjYramFOM3ErbUoKbkRlUWYzMThsclk0NVJxWHV1R294QzBhbWVoakRnTGxJUSs1d1kxR1NtRGRiaDFJOWZqMENVNkNzaFpsOXFtdgorelhjWGh4dlhmTUU4MUZsVUN1elRydHJFb1Bsc3dtVHN3ODNVY1lGNTFUak8zWWVlRno3RFRhRUhMUVVhUlBKClJtVzdxWE9kTGdRdGxIV0t3V2ppMFlrM0d0Ylc3NVBMQ2pGdEQzNytkVDFpTEtzYjFyR0VUYm42V3I0Nno4Z24KY1Q4cVFhS3pYRThoWjJPSDhSWjN1aFVpRHhZQUszdmdsYXJSdUFacmVYMVE2ZHdwYW9ZcERKa29XOXNjNXlkWApBTkJsYnBjVXhiYkpaWThLS0lRSURnTFdOckw3SVNxK2FnYlRXektFZEl0Ni9EZm1YUnJlUmlMbDlQMldvOFRyCnFxaHNHRlZoRHZlMFN6MjYyOU55amgwelloSmRUWXRpdldxbGl6VTdWbXBob1NrVnNqTGtwQXBiUUNtVm9vNkgKakJmdU1sY1JPeWI4TXJCMXZTNDJRU1MrNktkMytwR3JyVnh0akNWaWwyekhSSTRMRGwrVzUwR1B6LzFkeEw2TgprZktZWjVhNUdCZm00aUNlaWVNa3lBT2lKTkxNa1cvcTdwM200ejdUQjJnbWtldm1aU3Z5MnVMNGJLYlRoYXRlCm9sdlpFd253WWRxaktkcVkrOVM1UlNVQ0F3RUFBUT09Ci0tLS0tRU5EIFBVQkxJQyBLRVktLS0tLQ==" | base64 -d > release.pub
code language-bash openssl dgst -sha256 -verify release.pub -signature launcher.sha256 launcher.checksum
-
(Optional) Verify the checksum.
code language-bash shasum -a 512 -c launcher.checksum
-
Create the
config.yaml
file with the following contents.code language-yaml project: appname: "Acme Inc" # Company or site name that you provided when installing the agent application: phppath: php # Path to your PHP CLI interpreter (usually /usr/bin/php) magentopath: /var/www/html/example.com # Root directory where your Adobe Commerce application is installed (usually /var/www/html) checkregistrypath: /path/to/swat-agent/tmp # Temporary directory for the agent (usually /usr/local/swat-agent/tmp) issandbox: false # Enabling sandbox mode to use the agent on staging environment (true or false) database: user: your-adobe-commerce-db-username # Database user for your Adobe Commerce installation password: your-password # Database password for the specified user for your Adobe Commerce installation host: 127.0.0.1 # Database host for your Adobe Commerce installation dbname: your-adobe-commerce-db-name # Database name for your Adobe Commerce installation port: 3306 # Database port for your Adobe Commerce installation (usually 3306) tableprefix: # Table Prefix for your Adobe Commerce installation (default value: empty) enableautoupgrade: true # Enables automatic upgrade (restart required after an upgrade; agent does not check for upgrades if the option is disabled; true or false) runchecksonstart: true # Collect data on the first run (Usually 1) loglevel: error # Determines what events are logged based on severity (usually error)
-
Verify the installation.
code language-bash scheduler -v
code language-bash Version: 1.0.1 Success exit.
-
After downloading and installing the agent, you must configure it to run using one of the following methods:
Run the agent run-the-agent
We recommend configuring the agent to run as a service. If you have limited access to your infrastructure and do not have root permissions, then you must use cron instead.
Service service
-
Create a systemd unit file
(/etc/systemd/system/scheduler.service)
with the following configuration (replace<filesystemowner>
with the UNIX® user that owns the directory where the agent and the Adobe Commerce software are installed). If you downloaded the agent as a root user, change the directory and nested files owner.code language-config [Unit] Wants=network.target After=network.target [Service] Type=simple User=<filesystemowner> ExecStart=/path/to/agent/scheduler Restart=always RestartSec=3 [Install] WantedBy=multi-user.target
-
Launch the service.
code language-bash systemctl daemon-reload
code language-bash systemctl start scheduler
code language-bash systemctl enable scheduler
-
Validate that the service is up and running.
code language-bash journalctl -u scheduler | grep "Application is going to update" | tail -1 && echo "Agent is successfully installed"
Cron cron
If you do not have root permissions or do not have permissions to configure a service as root, you can use cron instead.
Update your cron schedule:
( crontab -l ; echo "* * * * * flock -n /tmp/swat-agent.lockfile -c '/path/to/agent/scheduler' >> /path/to/agent/errors.log 2>&1" ) | sort - | uniq - | crontab -
Uninstall
Run the following commands to uninstall the service from your system and remove all generated files:
-
Stop the scheduler.
code language-bash systemctl stop scheduler
-
Disable the scheduler.
code language-bash systemctl disable scheduler
-
Remove the scheduler service’s
systemd
unit file.code language-bash rm /etc/systemd/system/scheduler.service
-
Reload the
systemd
manager configuration.code language-bash systemctl daemon-reload
-
Reset any
systemd
units from a failed state.code language-bash systemctl reset-failed
-
Remove the scheduler service directory.
code language-bash rm -rf <CHECK_REGISTRY_PATH> #see SWAT_AGENT_APPLICATION_CHECK_REGISTRY_PATH in /etc/systemd/system/scheduler.service
-
Remove the scheduler binary file.
code language-bash rm /usr/local/bin/scheduler
If you configured the agent to run with cron instead, use the following instructions:
-
Remove the agent from the crontab list.
code language-bash crontab -e
-
Stop the running job.
code language-bash ps aux | grep scheduler
-
Remove the directory where you installed the agent.
code language-bash rm -rf swat-agent
Troubleshooting
Access keys not parsed properly
You may see the following error if your access keys are not parsed properly:
ERRO[2022-10-10 00:01:41] Error while refreshing token: error while getting jwt from magento: invalid character 'M' looking for beginning of value
FATA[2022-12-10 20:38:44] bad http status from https://updater.supportinsights.adobe.com/linux-amd64.json: 403 Forbidden
To resolve this error, try the following steps:
- Do a scripted install, save the output, and review the output for errors.
- Review the generated
config.yaml
file and verify that the path to your Commerce instance and PHP is correct. - Make sure that the user that is running the scheduler is in the file system owner Unix group or is the same user as the file system owner.
- Make sure that the Commerce Services Connector keys are installed correctly and try updating them to connect the extension to your system.
- Uninstall the agent after updating the keys and reinstall using the install script.
- Run the scheduler and see if you still receive the same error.
- If you still receive the same error, increase the log level in the
config.yaml
to debug and open a Support ticket.
SIGFAULT Error
If you see a SIGFAULT error when running binary, you probably do not run this as the file owner of Adobe Commerce and Agent files.
To resolve, please check if all the files inside the agent directory that have the same user as the fileowner that Adobe Commerce files have, and binary should be run under that user as well.
You can use the chown
command to change the files owner and switch to the appropriate user.
Make sure that your daemonization mechanism (Cron or System.d) runs the process under the appropriate user.