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 procedures presume that you have installed the Extension.

For more information, see the ZendHQ installation instructions.

Configuring the extension in Linux

The ZendHQ extension configuration file can be found at:

  • RPM systems: /etc/opt/zend/php{VERSION}zend/php.d/90-zendhq.ini, where {VERSION} is the PHP minor version without the dot separator (for example, 56, 71, 80, 81).
  • DEB systems: /etc/php/{VERSION}-zend/mods-available/zendhq.ini, where {VERSION} is the PHP minor version including the dot separator (for example, 5.6, 7.1, 8.0, 8.1).

The following code sample shows the default configuration contained in that file.

Copy

; ZendHQ extension configuration file

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; Global ZendHQ configuration
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Load the ZendHQ extension.
zend_extension = zendhq.so

; Name of the node.
; Specifies the name of the node. If empty or not specified, uses the node name
; reported by the uname() call, which is usually equal to the network name of this
; machine.
; The default value is empty = use the node name reported by the uname() call.
;zendhq.node_name = node1

; Name of the log file.
; Logging will be completely disabled, if this directive is missing or empty.
; Default value is empty = logging disabled.
;
; Notice that errors and warnings might still be output to the PHP log file even if
; zendhq logging is completely disabled.
zendhq.log_file = /opt/zend/zendphp/var/log/zendhq.log

; Defines how verbose the log file is.
;   0 - only error messages
;   1 - error and warning messages
;   2 - error, warning and info messages
;   3 - all above plus debug level 1 messages
;   4 - all above plus debug level 2 messages
;   5 - all above plus debug level 3 messages
; Default value is 2 = error, warning and info messages.
;zendhq.log_verbosity_level = 2

; Enables writing warning and error messages to the PHP error log
; Default value is 0 = disabled
;zendhq.use_php_error_log = 1

; The uri of the ZendHQ daemon.
; Default value is 'tcp://127.0.0.1:10090'.
; On Unix systems an UNIX domain socket with appropriate permissions could be
; used too.
; zendhq.daemon_uri=ipc:///tmp/z_ray.sock
zendhq.daemon_uri = tcp://zendhq:10090

; Directory where the ZendHQ extension can store temporary files
; The PHP process shall have full access to that directory.
; Default value is read from the TMPDIR environment variable.
;zendhq.tmp_dir = /tmp


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; Z-Ray configuration
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Globally enable or disable the Z-Ray functionality.
; Default value is 1 = enabled.
zendhq.zray.enable = 1

; Root directory where to look for Z-Ray plugins.
; Every Z-Ray plugin is expexted to be in a separate subdirectory and should be
; called 'zray.php'.
; Using the 'zray' subdirectoy is optional and reserved for the future.
;   <plugin_dir>/<plugin-A>/zray.php
;                <plugin-B>/zray/zray.php
; Default value is empty = plugins are disabled.
zendhq.zray.plugin_dir = /opt/zend/zendphp/plugins/enabled

; Enable or disable the collection of local variables for user functions traced
; by Z-Ray plugins.
; If the collection of local variables is enabled, then Z-Ray plugins can access
; all the local variables of a traced function via the '$context['local']' array.
;
; The content of local variables seen by Z-Ray might not match the code in the PHP
; script due to optimization done by opcache. For example, if a local variable
; is used to calculate the return value of a function, then the variable might be
; optimized out or the value may not represent the final return value.
;
; Default value is 1 = enabled.
;zendhq.zray.collect_locals = 1

; Enable or disable the collection of PHP errors, warnings and notices.
; The default value is 1 = enabled
;zendhq.zray.collect_errors = 1

; Enable or disable the collection of PHP exceptions.
; The default value is 1 = enabled
;zendhq.zray.collect_exceptions = 1

; Enable or disable the collection of stack traces for PHP errors, warnings and
; notices.
; The default value is 1 = enabled
;zendhq.zray.collect_backtrace.errors_warnings = 1

; Enable or disable the collection of stack traces for PHP exceptions.
; The default value is 1 = enabled
;zendhq.zray.collect_backtrace.exceptions = 1

; Maximum number of stack trace frames to collect.
; The default value is 0 = unlimited
;zendhq.zray.max_backtrace_frames = 100

; Enable or disable the collection of raw PHP output data.
; The default value is 1 = enabled
;zendhq.zray.collect_raw_output = 1


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; Code Tracing configuration
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Globally enable or disable the Code Tracing functionality.
; Default value is 1 = enabled
zendhq.codetracing.enable = 1

; Enable or disable Code Tracing using a request parameter
; If enabled, allows collection of Code Tracing traces using a request parameter.
; Do not enable this parameter in production systems.
; Default value is 0 = disabled
;zendhq.codetracing.enable_request = 1

; Maximum length of string values to store in Code Trace. Longer strings will be
; truncated.
; Default value is 48
zendhq.codetracing.max_string_length = 48

; Enable array contents recording.
; Default value is 1 = enabled
;zendhq.codetracing.trace_arrays = 1

; Maximum number of array elements to store in Code Trace. Longer arrays will be
; truncated.
; Default value is 10
zendhq.codetracing.max_array_elements = 10

; Maximum depth of arrays to store in Code Trace. Deeper nesting levels will be
; truncated.
; Default value is 2
zendhq.codetracing.max_array_depth = 2

; Minimum time between Code Trace collections in number of seconds. This parameter
; ensures that the PHP process is not overloaded by too many Code Trace requests.
; Default value is 1
;zendhq.codetracing.max_freq = 1

; Enable execution time measurment.
; Default value is 1 = enabled
;zendhq.codetracing.trace_time = 1

; Enable memory usage data collection.
; Default value is 1 = enabled
;zendhq.codetracing.trace_memory_usage = 1

; Enable source file collection.
; Default value is 1 = enabled
;zendhq.codetracing.trace_source_lines = 1

; Enable internal functions collection.
; Default value is 1 = enabled
;zendhq.codetracing.trace_internal_functions = 1

; Enable user functions call collection.
; Default value is 1 = enabled
;zendhq.codetracing.trace_user_functions = 1

; Enable tracing include and require calls.
; Default value is 1 = enabled
;zendhq.codetracing.trace_includes = 1

; Enable function call argument collection.
; Default value is 1 = enabled
;zendhq.codetracing.trace_arguments = 1

; Enable function return value collection.
; Default value is 1 = enabled
;zendhq.codetracing.trace_return_values = 1

; Enable PHP exception data collection.
; Default value is 1 = enabled
;zendhq.codetracing.trace_exceptions = 1

; Enable output data writing collection.
; Default value is 1 = enabled
;zendhq.codetracing.trace_write = 1

; Enable HTTP response headers collection.
; Default value is 1 = enabled
;zendhq.codetracing.trace_headers = 1

; Enable PHP error collection.
; Default value is 1 = enabled
;zendhq.codetracing.trace_errors = 1

; Enable Monitoring Event recording.
; Default value is 1 = enabled
;zendhq.codetracing.trace_events = 1


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; Monitoring configuration
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Globally enable or disable the Monitoring functionality.
; Default value is 1 = enabled
zendhq.monitor.enable = 1

; PHP Super-global variables to include in event reports
; Specifies a string, where individual characters have the following meaning:
;   'S' - include the $_SERVER variable
;   'R' - include the $_REQUEST variable
;   'G' - include the $_GET variable
;   'P' - include the $_POST variable
;   'E' - include the $_ENV variable
;   'C' - include the $_COOKIE variable
;   'F' - include the $_FILES variable
; Default value is "SRC" (include $_SERVER, $_REQUEST, and $_COOKIE variables)
zendhq.monitor.report_super_globals = SRC


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; Job Queue configuration
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Globally enable or disable the Job Queue functionality.
; Default value is 1 = enabled
zendhq.jobqueue.enable = 1

; Connection timeout to the Job Queue daemon in number of seconds
; Default value is 3 seconds
zendhq.jobqueue.daemon_connection_timeout = 3
Note Codetracing configuration has no effect at this time; support for codetracing will be included in a later release of ZendHQ.

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.

Configuring the extension in Windows

Update zendhq.ini for the extension and zendhqd.ini file for the daemon. In this scenario, let’s assume that the IP address of the ZendHQ Windows machine with the extension is 10.0.0.1, and the Linux instance with the ZendHQ daemon is 10.0.0.2. Replace these IP addresses with your own!

Identify the following configuration files:

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

  • Windows MSI installation-based ZendHQ Extension ini script for PHP 8.3:
    C:\Program Files\Zend\ZendPHP\8.3\etc\conf.d\zendhq.ini

  • If you installed the extension using the zendphp_install.ps1 script, then the zendhq.ini file is:
    <installation root>/etc/conf.d/zendhq.ini
    Depending on your setup, it is possible to use it from there. Or, if you use only php.ini, then add directives for the ZendHQ extension to php.ini.

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://10.0.0.2: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://10.0.0.2:10090 # set your IP address here!

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

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

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

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

    • The log_file directive needs to point a file where the ZendHQ extension can store its log.

    • Both directories need to 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.

Restarting PHP after configuration changes

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

To restart Apache, execute the following command:

$ sudo systemctl restart apache2

To restart your PHP-FPM pool, execute the following commands for the applicable version:

# RPM systems (Replace {VERSION} by the PHP minor version without the dot separator)
$ sudo systemctl restart php{VERSION}zend-fpm
# DEB systems (Replace {VERSION} by the PHP minor version)
$ sudo systemctl restart php{VERSION}-zend-fpm