PHP Troubleshooting in Windows Azure Web Sites

The need to diagnose and troubleshoot application’s failures often comes up during deployment to a hosting environment. Some configuration settings in hosting server may differ from what application expects. Often it is not as easy to figure out the cause of the problem in a hosting environment as it is on a development machine.  I found the following techniques useful when troubleshooting errors in PHP applications hosted in Windows Azure Web Sites.

1. phpinfo()

This is the most obvious, but very often the most helpful diagnostics tool. The output of this function provides a lot of information about the PHP runtime. Use it to determine what PHP extensions are enabled, what are the PHP configuration settings and what values are stored in server environment variables.

To use the phpinfo() function create a new php file that contains just one line:

<!--?php phpinfo(); ?-->

Name this file with some non-obvious name (don’t name it phpinfo.php) and upload it to the root directory of your site. Request this file from a web browser and analyze the output.

The output from phpinfo may expose security sensitive information! Always delete this file from the site’s root directory after you are done with it.

2. wincache.php

WinCache extension is by default enabled for PHP web sites. To check how opcode and user cache work and what is the current content of the cache use wincache.php script that can be downloaded from the wincache source code repository. Get the script and the edit it by specifying the user name and password that will be used to protect the access.

/**  * ======================== CONFIGURATION SETTINGS ==============================
* If you do not want to use authentication for this page, set USE_AUTHENTICATION to 0.
* If you use authentication then replace the default password.
*/
define('USE_AUTHENTICATION', 1);
define('USERNAME', 'someusername');
define('PASSWORD', 'somepassword');

After that upload it to the root directory of a website and request this page from a web browser. The output will look similar to below:

Always protect the wincache.phpscript by using the built-in authentication or other authentication mechanisms. Leaving this script unprotected may compromise the security of your web application.

3. PHP Error Log

PHP runtime in Windows Azure is configured to save application errors into a log file located in the /LogFiles directory under FTP root of a site.

If application does not work or returns a blank page – check this file as it may contain the details of an error. I also check this file from time to time for my live sites to make sure the site is running properly.

It is also possible to overwrite the default location of the error log file. For that create a file called .user.ini and add the following line to it:

error_log=D:\Home\site\wwwroot\php_errors.log

Upload this file to the root directory (wwwroot) of your web site.

4. PHP display_errors

PHP runtime directive display_errors is used to output the errors in the HTTP response. For production deployments it should be set to “Off” in order to not show error details to web site visitors. For development and debugging purposes you can temporary set it to On by using .user.ini file:

display_errors=On
html_errors=On
error_reporting = E_ALL

When application has an error it will be output in the web browser.

I usually turn display_errors off as soon as I got all the necessary information from the error output.

5. HTTP logs, Detailed Error Messages, Failed Request Tracing

By default HTTP logging, detailed error messages and failed request tracing are turned off for a site. To turn them on use the CONFIGURE page in Windows Azure Portal:

Once enabled the log files will appear in the following directories under site’s FTP root:

•  HTTP log files will appear in the /LogFiles/http/RawLogs;
• Detailed errors will appear in the /LogFiles/DetailedErrors;
• Failed Request Tracing logs will be in /LogFiles/W3SVC#########/;

6. XDebug PHP Extension

Xdebug is a very popular PHP extension that helps with debugging and profiling of PHP scripts by providing a lot of valuable debug information. To enable Xdebug for a site in Windows Azure download the appropriate build of Xdebug extension from downloads page. If your site uses PHP 5.3 then download “5.3 VC9 (32 bit)”. If your site uses PHP 5.4 then download “5.4 VC9 (32 bit)”. Use 32 bit build even if your Windows OS is 64 bit. Do not use thread safe (TS) builds.

Upload the php_xdebug_####.dll file to /site/wwwroot/bin directory. If bin directory does not exist then create it. After that use the CONFIGURE tab in Windows Azure Portal to enable xdebug extension:

With xdebug enabled you will be getting more detailed error messages and call stack:

7. ClearDB stats

ClearDB service that provides MySQL database hosting is now integrated into the Windows Azure Portal. It is now possible to buy and manage your MySql databases from the portal. Also the billing is integrated, meaning that ClearDB charges will be billed on Azure subscription.

To access ClearDB management page use the ADD-ONS tab.

From there you can open the ClearDB query performance page as well as access other database management information

I wonder why the query performance chart shows such a light load on my database. I guess this maybe because of a wincache user cache which loads all the blog content in memory so there are very few or none database access operations.