ZendHQ Extension for ZendPHP

The primary functionality of ZendHQ consists of the ZendHQ daemon, 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 will collect information during requests and send it to the ZendHQ service.

Installing the extension

Please see the ZendHQ installation instructions.

Configuring the extension

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.

; ZendHQ extension configuration file
; priority=90

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

; Load the ZendHQ extension.
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://127.0.0.1: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 = 0

; 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

; 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.
; Defult value is 2
zendhq.codetracing.max_array_depth = 2

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; 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

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.

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