Innovate faster and cut risk with PHP experts from Zend Services.
Learn PHP from PHP experts with free, on-demand, and instructor led courses.
Submit support requests and browse self-service resources.
Matthew Weier O’Phinney
PHP code tracing is important for teams who need to identify and resolve issues in production. In this blog, we give an overview of code tracing, why it's important for PHP applications, and walk through how to perform code tracing with ZendPHP and ZendHQ.
Code tracing is a feature of software monitoring, whereby the program produces a log of information regarding the program’s execution, typically in the form of language directives and function calls. Software developers can then use this information to perform root cause analysis of software errors.
Considering PHP applications are generally web applications, and you may or may not know who experienced the error or how they encountered it, a code trace gives you valuable insight to ensure you are able to resolve the issue and prevent it from occurring again.
When an error occurs in a production application, a developer often has little to no knowledge of what led to the error. If they have set up copious logging, they may be able to identify some of the application input from the point of the request initialization to the error, but often this information will omit pieces of context that can be useful for diagnosis.
Additionally, while logging in a production application is highly useful for such purposes, it also introduces a lot of application overhead (logging usually involves some form of input/output or network operations, each of which lead to increased execution time and memory), and may be difficult to query in real time. Finally, while logs can help in diagnosing an issue, they generally will not notify you of issues.
Application monitoring can assist with this latter aspect. An Application Performance Monitoring (APM) tool allows infrastructure teams to define conditions of interest: long execution times, high memory usage, errors, failure to connect to integrated services, and more. When a rule is matched, the APM tool can log the issue, and, often, push notifications to the infrastructure team (e.g., via chat ops, mobile push notifications, and more).
When an APM tool is able to provide code tracing, you get an even more valuable tool: you can tell the APM rule that you want a trace captured, which then gives you the full context for the request that triggered the rule: function calls (including their parameters and return values), language directives called, files and libraries included, and more.
This information makes it far easier to:
Starting with version 1.2.0 of ZendHQ, we now offer Code Tracing as a standard part of our observability tooling, which also includes Monitoring and Z-Ray.
See How Code Tracing Works in ZendHQ
If you already use ZendHQ, you will need to:
These are typically done by using your operating system package manager’s “update” or “upgrade” functionality.
If you are not yet using ZendHQ, refer to our documentation for installation instructions.
By default, Code Tracing is enabled in both the ZendHQ extension for ZendPHP and in the ZendHQ daemon. You can toggle it on and off via the following settings:
The ZendHQ GUI will auto-update on launch to pull in the new features supporting Code Tracing.
Code Tracing in ZendHQ is tied to the Monitoring feature. When configuring severities for a given monitoring rule, you will now see a checkbox to “Trace code” under the “Actions when triggered” heading.
When a monitoring rule is matched that captures a trace, you will see each of the following:
When you click on a code trace, you will get a tree view.
You can use the toggles next to the “Trace” button to fully expand the tree or fully collapse it. Alternately, you can manually expand individual branches of the tree yourself by clicking the toggle to the left of each branch.
Since trees can be large, you may want to search for items of interest. Code Tracing offers four different ways to search the tree and narrow the results:
You can combine the searches as well; combining them will return any results that match any of the conditions; in other words, selecting multiple conditions will not narrow to those that only match all of them.
When you have searched, you can use the next/previous buttons next to the count of results to move between matching lines in the tree; doing so will expand the tree when necessary.
Clicking on any trace line will open a drawer with details about that line. These details vary based on the line type; for example, the details for an “include” directive will only detail the file included, where the directive was called, and exclusive time and memory usage.
For a function call, you will get far more details. All function calls detail the arguments provided, and the return value or exception thrown; this information can also be copied to your system clipboard. If the function call was related to a static class method or an instance class method, you’ll get details about the class, which instance was used, and more. Finally, if a particular function was called multiple times in the request, you will get a list of additional invocations. Each of these lines may be clicked on to take you to that invocation in the trace tree, and detail its own specific arguments and return value.
Code Tracing provides an important tool for helping your DevOps or Platform Engineering teams to identify production issues, as well as diagnose them. The information captured in a code trace allows teams to create reproducible tests, which can then be used to both fix the issue, as well as ensure it never happens again.
Additionally, with information such as execution time and memory consumption, you can use a combination of Monitoring and Code Tracing as a way to profile your production code and identify bottlenecks. These will allow you to identify places you may want to provide caching, or optimize database queries or web service calls.
Try ZendPHP and ZendHQ for FreeReady to try ZendPHP and ZendHQ? Start your free trial today.Get Started
Ready to try ZendPHP and ZendHQ? Start your free trial today.
Zend Product Manager, Zend by Perforce
Matthew began developing on Zend Framework (ZF) before its first public release, and led the project for Zend from 2009 through 2019. He is a founding member of the PHP Framework Interop Group (PHP-FIG), which creates and promotes standards for the PHP ecosystem — and is serving his second elected term on the PHP-FIG Core Committee.