Configuring the ZendHQ Extension for ZendPHP

The primary functionality of ZendHQ consists of the ZendHQ daemon (service), and one or more ZendPHP instances configured with the ZendHQ extension. When the ZendHQ extension is enabled and configured to point at a ZendHQ service, it collects information during requests and sends it to the ZendHQ service.

Installing the extension

The following configuration procedures require that you have installed the Extension.

For more information about installation on Windows, Linux, or IBM i, see the ZendHQ installation instructions first.

How to configure the extension

The ZendHQ extension configuration file can be found at:

  • RPM systems:
    /etc/opt/zend/php{VERSION}zend/php.d/90-zendhq.ini
    Replace {VERSION} with the PHP minor version without the dot separator (for example, 72 or 83).

  • DEB systems:
    /etc/php/{PHP_VERSION}-zend/mods-available/zendhq.ini
    Replace {PHP_VERSION} with the PHP minor version including the dot separator (for example, 7.2 or 8.3).

  • IBM i systems:
    /QOpenSys/etc/php/{VERSION}zend/conf.d/90-zendhq.ini
    Replace {VERSION} with the PHP minor version without the dot separator (for example, 72 or 83).

  • Windows MSI installation:
    C:\Program Files\Zend\ZendPHP\{PHP_VERSION}\etc\conf.d\zendhq.ini
    Replace {PHP_VERSION} with the PHP minor version including the dot separator (for example, 7.2 or 8.3).

  • Windows zendphp_install.ps1 script installation:
    <installation root>/etc/conf.d/zendhq.ini
    Depending on your setup, it is possible to use the script from there. Alternatively, if you use only php.ini, then directives for the extension can be added and modified in php.ini.

The following list shows the primary configuration values:

  • zendhq.log_file: If you are in Docker, change this value to /proc/self/fd/2.
  • zendhq.daemon_uri: Set this value to the server and port where the ZendHQ service is running, a value corresponding to the zendhqd.daemon_uri on the machine running the ZendHQ service.
  • zendhq.zray.enable: Toggle this option off if you want to disable Z-Ray data originating from this server.
  • zendhq.monitor.enable: Toggle this off if you want to disable emitting monitoring data from this server.

  • zendhq.codetracing.enable: Toggle this off if you want to disable emitting Code Tracing data from this server.

  • zendhq.jobqueue.enable: Toggle this off if you want to disable the JobQueue functionality.

How to run the extension on a different machine than the daemon

When the ZendHQ Daemon and ZendHQ Extension are running on different machines, additional configuration steps are required to establish a connection between the Daemon and the Extension. These instructions use a ZendHQ Daemon on Linux as an example, but the daemon can also be located on IBM i. The ZendHQ Daemon for Windows will be included in an upcoming release. For now, the ZendHQ Daemon is supported only on Linux and IBM i, meaning, this configuration change is currently always required if your ZendHQ Extension is located on a Windows machine.

Identify the following configuration files:

  • Linux zendhqd.ini script for the daemon:
    /opt/zend/zendphp/etc/zendhqd.ini

  • The zendhq.ini script for the extension. For OS-specific locations, see the main configuration procedure above.

Configure the following settings:

  1. In zendhq.ini, enter the IP address of the Linux instance with the ZendHQ daemon here:

    • zendhq.daemon_uri = tcp://{YOUR_DAEMON_IP}:10090 # set your IP address here!

  2. In zendhqd.ini, enter the IP address of the Linux instance with the ZendHQ daemon here:

    • zendhqd.daemon_uri = tcp://{YOUR_DAEMON_IP}:10090 # set your IP address here!

    • zendhqd.daemon_pub_uri = tcp://{YOUR_DAEMON_IP}:10092 # set your IP address here!

  3. Adjust zendhqd.websocket.interface to make the ZendHQ daemon accessible for ZendHQ UI.

For Windows only:

If your setup is fully manual without using either the PowerShell option or the MSI installer, then also configure the zendhq.cache_dir and zendhq.log_file directives in the zendhq.ini file manually:

  • Point the cache_dir directive to a folder where the ZendHQ extension stores its local configuration cache.

  • Point the log_file directive to a file where the ZendHQ extension can store its log.

  • Verify that both directories exist and have correct permissions for ZendHQ to access them. The ZendHQ extension does not create folders by itself.
    If you have used the MSI or PowerShell installer, then the installer created these folders in default locations.

How to restart PHP after configuration changes

Whenever you make configuration changes, restart either Apache (if using Apache with mod_php), or your PHP-FPM pool (Linux-only).

Linux

To restart Apache, execute the following command:

$ sudo systemctl restart apache2

To restart your PHP-FPM pool, execute one of the following commands:

# For RPM systems, replace {VERSION} by the PHP minor version without the dot separator:
$ sudo systemctl restart php{VERSION}zend-fpm
# For DEB systems, replace {VERSION} by the PHP minor version:
$ sudo systemctl restart php{VERSION}-zend-fpm

IBM i

To restart Apache on the Green Screen, enter GO ZENDPHP/ZPMNUAPA options 3/4/5:

  1. Start

  2. Stop

Windows

First restart Apache and then restart IIS.

To restart Apache through the GUI:

  1. From the Windows menu, open Run.

  2. Enter services.msc .

  3. In the Services window, right-click the Zend Apache 2.4 service and select Restart.

To restart Apache through the command prompt (or PowerShell) , enter the following commands:

net stop "Zend Apache 2.4" 
net start "Zend Apache 2.4"

The service is named “Zend Apache 2.4“ if installed using MSI installer. If not, then the service name has been set by the user.

To restart IIS:

  • Either use the IIS manager to restart IIS.

  • Or enter the following commands at the command prompt (or PowerShell):

net stop /y WAS 
net start /y WAS