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('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:


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:

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.

5 thoughts on “PHP Troubleshooting in Windows Azure Web Sites”

  1. Hi,

    i am using windows azure server for php application.In this my mail function is not working.Kindly send me any solution for that.At the same time in database all the table auto increment values are incremented by 10 insted of 1.Let me know if any solution for that.your blog is very clear to understand.

  2. Hi – and thanks for this informative info about debugging.

    Is there a way to get console access to such a site also? In the event that one need to install some packages, and it must be done from a command promt.


  3. Ah…I found the answer!
    The console are available using this path:

    https://{site name} (in other words, add .scm in front of the site name).

    Pick ‘Debug console’ on the top.

  4. You forgot to mention you need to add
    log_errors = on
    for errors to get written to php_errors.log.

    error_log = d:\home\LogFiles\php_errors.log
    is not enough for that to happen.

  5. In Azure App Service wincache.php located in D:\Program Files (x86)\IIS\Windows Cache for PHP folder. You can copy it to your site root folder and see cache status in your browser.

Leave a Reply

Your email address will not be published. Required fields are marked *