Support Magic With Z-Ray

Z-Ray is a must-have for every PHP developer. With Z-Ray, you get immediate app execution insight, in the browser – no need for tailing log files, no extra apps or setup, not even a browser plugin is required. Performance info, memory consumption, SQL queries, profiling or detailed errors, and much more are all displayed in Z-Ray. According to PHP developers, Z-Ray becomes as important as a debugger – you really miss it when it's not available.

Want to see it live? Just try it out with a Magento shop system on our demo server. (Hint: Look at the bottom of the page for Z-Ray. Don’t hesitate to try it out!) 

Figure 1: Z-Ray for Magento, on a live demo server

The magic of Z-Ray lies in the Z-Ray PHP extension. This extension hooks into the execution flow and allows to run custom PHP code (which is the Z-Ray plugin) before and after every function and method is executed in the app, without changing the original source code. That’s the important fact. Using Z-Ray, you enable metrics collection (e.g. how often a function is being called) and profiling on a very detailed level without modifying or adding complexity to the app itself. It just works out-of-the-box.

Z-Ray – Not Only in Development

Can Z-Ray help you on a live production system? Can it help your customers that have specific issues?

Z-Ray comes in three modes: Enabled, Disabled, and Selective. In development, you probably need it Enabled. OK, and Disabled is turned off, but what is Selective? Well, it is there for addressing the questions mentioned above: get Z-Ray insight on a production environment. The Z-Ray Selective Mode allows you to enable Z-Ray for specific IPs or URLs, and for a specific time duration.

In the Zend Server UI, choose Selective in Z-Ray | Mode, save, and restart Zend Server. Now switch to the Selective Access tab and create a new access token by clicking on Allow Selective Access. Add the required information. On the last page, please make sure that “Display Z-Ray on all pages open in a browser” is NOT checked – otherwise the Z-Ray toolbar is being displayed for the customer, and usually you’d like to avoid that. 

Figure 2: To use Z-Ray in production, choose Selective mode and create a token

The token you have just created is a GET parameter to be added to the URL itself for creating a Z-Ray snapshot. If you want the customer to participate in the process of reproducing the problem, share the token and ask them to add it to the URL and re-trigger the request. A Z-Ray snapshot will be created in the background and can immediately be examined in the Z-Ray Live! section on the Zend Server admin console. 

Figure 3: Z-Ray Live! - Z-Ray snapshot is displayed in Zend Server GUI 

That’s powerful! Zend Server triggers only the Z-Ray Snapshot for this unique URL, for this specific user, so that there is no disruption for other users accessing the system. Now the support team or developers can see exactly what the customer experience was. Troubleshooting has never been simpler.

Turbocharge Z-Ray

Z-Ray functionality can be extended by adding plugins. In the Zend Server UI under Plugins | Gallery, you can find framework specific plugins: Zend Framework, Symfony, WordPress, Drupal, and Laravel are just a few examples. Other plugins are for Magento, OpCache, Redis, and more. Here's a full list of available Z-Ray plugins. 

Figure 4: Zend Server plugins in the Gallery

By installing Z-Ray plugins, Zend Server auto-detects whether the appropriate framework is being used. If so, typically a new tab in the Z-Ray toolbar exposes specific details collected for the framework.

Z-Ray and Monitoring

Zend Server has powerful APM capabilities. If a request takes too long, a script consumes too much memory, or if just an Exception isn’t caught, Zend Server triggers events in such cases and collects detailed information about the environment. When monitoring rules are defined and enabled, Zend Server observes all the requests and stores relevant information when an event is triggered.

Recently, we introduced a new Z-Ray plugin, EventTrigger. When installed, Z-Ray creates an ad-hoc event for a specific end-user request. When an event is registered, Zend Server stores the request context, which can be analyzed in Zend Server GUI, allowing easier troubleshooting. Moreover, via the Zend Server GUI, you can also debug this request with Zend Studio or PHP Storm. Better practice would be to export the debug session to a dedicated test and debugging server. 

Figure 5: Zend Server Event created via Z-Ray, using the new EventTrigger plugin

The EventTrigger plugin implementation is actually very simple:

• It calls zend_monitor_custom_event() – a Zend Server PHP API function that allows to trigger a monitoring event from a PHP script

• It has no UI part, thus isn’t displayed in the Z-Ray bar. You should be able to locate the event in the Zend Server Events tab The source code of the plugin is available here.

Trace it to the Limit

If it’s difficult to reproduce and debug an issue on an alternate host, or if real live data is required, then there is an elegant alternative for debugging in Zend Server: Code Tracing. Code Tracing can be compared to a flight recorder in an airplane. The complete context of a request is stored in a Code Trace. Every function and method call are saved, including arguments, return parameters, object context, execution time, memory consumption, errors, and warnings. 

Figure 6: An example for Code Trace functions tree section

To activate Code Tracing for events created by the EventTrigger plugin, you must enable it in Monitoring | Event Rules on Zend Server UI. Choose the Custom Event rule in either a dedicated app or globally, and activate Trace Code for notices.

Start now

Give it a try. It’s powerful, helpful, and fun to use. If you already have a Zend Server license, go ahead and install Z-Ray EventTrigger. If you haven’t got it yet, choose one of the following: download the trial version from our website, get it on Amazon AWS, or pull and run the official Docker image (php-zendserver) on Docker Hub.

Happy coding!

More information about Z-Ray can be found here.