Install APM Insight PHP Agent in Linux (PHP version 7.0 and above)

Prerequisites

Agent Versions:

  • PHP Agent v3.5.1: Compatible with PHP versions 7.0 - 8.1.
  • PHP Agent v4.1 - v4.3: Compatible with PHP versions 7.0 - 8.2.
  • PHP Agent v4.4 and above: Compatible with PHP versions 7.0 - 8.3.
Note:
  • APM Insight PHP Agent v4.1 and above requires the installation of an Applications Manager Data Exporter.
  • From Applications Manager Data Exporter v1.4.1, a new monitor will be generated for each cloud instance, using the cloud instance ID as the hostname. Consequently, existing monitors associated with old hostnames will become inactive. This is applicable only for applications hosted in cloud platforms.

New Monitor/Upgrade Considerations:

  • For users of PHP versions 7.0 to 8.1, both APM Insight PHP Agent v3.5.1 and the newest version are fully compatible. To add a new monitor or upgrade to the latest APM Insight Agent version, follow the steps below:
    1. Uninstall the older agent if APMInsight PHP agent version below 4.1 is used.
    2. Install Applications Manager Data Exporter (for Linux or Windows) to enable communication with the Applications Manager server.
    3. Install the latest APM Insight PHP Agent Version as mentioned in here.
    4. During the agent upgrade, ensure you specify the current monitor's Application Name to maintain data collection with the existing monitor. If not specified, a new monitor will be created with the Default Application Name.
Recommendations:
  • For new monitoring setups, we recommend using PHP Agent v4.1 or above to access the latest features.
  • If you have an existing monitoring setup, you have the option to continue with v3.5.1 or transition to v4.1 or higher as needed.

In summary, you can opt for v3.5.1 for existing configurations or v4.1 and above to benefit from the latest features, which require additional setups. Please be aware that PHP 8.2 is exclusively supported by v4.1 and above.

Installation instructions

The PHP agent can be installed using one of the following methods:

Instructions for installation using the command-line interface

  1. Download the installation script.

    wget -O InstallAgentPHP.sh https://www.manageengine.com/products/applications_manager/54974026/InstallAgentPHP.sh

  2. Execute the installation command with the required options.

    sudo sh InstallAgentPHP.sh -lk [LICENSE KEY]

    or

    sudo sh InstallAgentPHP.sh -license.key [LICENSE KEY]

    [LICENSE KEY] - License key from Applications Manager. (Mandatory)

  3. Restart your web server and the FastCGI Process Manager (FPM), if used.
     
    Note: 
    Given below are the other available options and their descriptions:
     
    Option Description
    -php.install_path The custom installation path of the PHP agent.
    -lk, -license.key The license key of the account.
    -zpa.application_name Name of the application.
    Note: The default name is PHP-Application.
    -zpa.status_port The inter-process communication status port number.
    -zpa.data_port The inter-process communication data port number.
    -zpa.remote_exporter_ip The IP Address of the device on which the data exporter is currently running.
    -zpa.remote_exporter_hostname The hostname of the device on which the exporter is running.
    -zpa.span_limit The maximum number of spans to be captured (Default value: 10000).

Instructions for installation using environment variables

  1. Download the installation script.

    wget -O InstallAgentPHP.sh https://www.manageengine.com/products/applications_manager/54974026/InstallAgentPHP.sh

  2. Set the required options.

    export APPMANAGER_LICENSE_KEY=[LICENSE KEY]

    [LICENSE KEY] - License key from Applications Manager. (Mandatory)

  3. Execute the installation command.

    sudo -E sh InstallAgentPHP.sh

  4. Restart your web server and the FastCGI Process Manager (FPM), if used.
     
    Note: 
    Given below are the other available options and their descriptions:
     
    Option Description
    PHP_INSTALL_PATH The Custom Installation Path of the PHP agent.
    APPMANAGER_LICENSE_KEY The license key of the account.
    ZPA_APPLICATION_NAME Name of the application.
    Note: The default name is PHP-Application.
    ZPA_STATUS_PORT The inter-process communication status port number.
    ZPA_DATA_PORT The inter-process communication data port number.
    ZPA_REMOTE_EXPORTER_IP The IP Address of the device on which the data exporter is currently running.
    ZPA_REMOTE_EXPORTER_HOSTNAME The hostname of the device on which the exporter is running.
    ZPA_SPAN_LIMIT The maximum number of spans to be captured (Default value: 10000).

Instructions for installation using script

  1. In the Applications Manager web client, go to the APM tab → Add New Monitor → PHP and copy the License Key present in the helpcard.
  2. Download the APM Insight PHP Agent from the download page in the required Linux server.
  3. Start by logging into root.
  4. Extract the downloaded Agent zip file into the /opt directory. This will create a sub-directory called zpa.

    $ cd /opt
    $ unzip [Downloaded_Agent_Path]/[Downloaded_Agent_Filename].zip

  5. Execute the below command:
    • For PHP Agent v4.5 and above

      $ sh /opt/zpa/bin/agent_php.sh install -license.key [LICENSE KEY]

      [LICENSE KEY] (Mandatory) - The license key copied from Applications Manager. 
    • For PHP Agent versions below v4.5

      $ sh /opt/zpa/bin/agent_php.sh install

  6. Restart your web server and the FastCGI Process Manager (FPM), if used.

Instructions for installation in Docker

Note: Please verify that the instructions mentioned above have been followed.

Follow the steps given below to install the PHPAgent and Applications Manager's DataExporter in the Docker Container:

  1. Add the PHP Agent install command with install arguments in the Dockerfile.
  2. Add the Applications Manager's DataExporter install command with install arguments in the Dockerfile.
  3. Start the DataExporter from the Entrypoint script.

Example Dockerfile script:

FROM php:7.4-fpm-bullseye
#
#YOUR CODE
#
#prequsites (ignore if already installed)
RUN apt-get update && apt-get install -y wget unzip procps
#installing PHP AGENT
RUN wget -O InstallAgentPHP.sh https://www.manageengine.com/products/applications_manager/54974026/InstallAgentPHP.sh
RUN sh InstallAgentPHP.sh -lk <licensekey> -zpa.application_name <PHP-Application>
#installing AppManagerDataExporter (This is mandatory for PHP Agent to work)
RUN wget -O InstallDataExporter.sh https://www.manageengine.com/products/applications_manager/54974026/InstallDataExporter.sh
RUN sh InstallDataExporter.sh -root -nsvc -license.key <licensekey> -apm.host <apm_host> -apm.port <apm_port> -apm.protocol.https false
#entrypoint script
COPY ./example-entrypoint.sh /example-entrypoint.sh
ENTRYPOINT [ "sh","/example-entrypoint.sh" ]

Example Entrypoint script:

#!/bin/sh
# Start AppManagerDataExporter
sh /opt/AppManagerDataExporter/bin/service.sh start
#
#YOUR CODE
#
php-fpm