Using Failed Request Tracing to Trace Rewrite Rules
IIS 7.0 and above Failed Request Tracing (FRT) is a powerful tool for troubleshooting request-processing failures. FRT can be used with the URL rewrite module to trace how rewrite rules were applied to the request URL. This walkthrough will guide you through how to use FRT to troubleshoot and debug URL rewriting rules. For more information about Failed Request Tracing, see this article.
Prerequisites
This walkthrough requires the following prerequisites:
- IIS 7.0 or above with ASP.NET and "Tracing" role services enabled
- URL rewrite Go Live release installed
Setting up a test Web page
To demonstrate how the URL rewrite module works, we will be using a simple test ASP.NET page. This page reads the Web server variables and outputs their values in the browser.
Copy the following ASP.NET code and put it in the %SystemDrive%\inetpub\wwwroot\
folder in a file called article.aspx:
<%@ Page Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>URL Rewrite Module Test</title>
</head>
<body>
<h1>URL Rewrite Module Test Page</h1>
<table>
<tr>
<th>Server Variable</th>
<th>Value</th>
</tr>
<tr>
<td>Original URL: </td>
<td><%= Request.ServerVariables["HTTP_X_ORIGINAL_URL"] %></td>
</tr>
<tr>
<td>Final URL: </td>
<td><%= Request.ServerVariables["SCRIPT_NAME"] + "?" + Request.ServerVariables["QUERY_STRING"] %></td>
</tr>
</table>
</body>
</html>
After copying this file, browse to http://localhost/article.aspx
and check that the page was rendered correctly in a browser.
Configuring rewrite rules
Locate a web.config file in %SystemDrive%\inetpub\wwwroot\
folder or create one if it does not exist. Open web.config file and add the following section inside of the <system.webServer>
element:
<rewrite>
<rules>
<rule name="Fail bad requests">
<match url="." />
<conditions>
<add input="{HTTP_HOST}" negate="true" pattern="localhost" />
</conditions>
<action type="AbortRequest" />
</rule>
<rule name="Rewrite to article.aspx">
<match url="^article/([0-9]+)/([_0-9a-z-]+)" />
<action type="Rewrite" url="article.aspx?id={R:1}&title={R:2}" />
</rule>
</rules>
</rewrite>
- The "Fail bad requests" rule aborts HTTP connection if the host header of HTTP request does not match "localhost"
- The "Rewrite to article.aspx" rule rewrite urls from this format
http://localhost/article/234/some-title
to this formathttp://localhost/article.aspx?id=234&title=some-title
.
Check that the rules are configured correctly by opening a browser and making a request to http://localhost/article/234/some-title
. If rules were setup correctly then you should see the following response in browser:
Configure Failed Request Tracing
Now enable failed request tracing for a "Default Web Site" (see this article for step by step instructions on how to enable FRT). After you enable failed request tracing, we will create an FRT rule for tracing events specific to the URL rewrite module.
To create an FRT rule in IIS Manager follow these steps:
- Click on "Failed Request Tracing Rules" icon to get to the list of FRT rules.
- Click on the "Add …" action to bring up the FRT rule creation wizard.
- On first page of the wizard choose "All content (*)"
- Click "Next" and specify the status code(s) as "200-399"
- Click Next and then uncheck all the trace providers except "WWW Server" and then uncheck all the provider areas except "Rewrite"
- Click on Finish to save the FRT rule.
If the Failed Request Tracing was installed after URL rewrite module, the "Rewrite" area in Trace Providers may not be available. If you do not see "Rewrite" area listed there, go to Add/Remove programs and then run URL rewrite module installer in repair mode.
Analyzing Failed Request Tracing log file
After the FRT rule has been created, make a request to http://localhost/article/234/some-title
. This will create an FRT log in %SystemDrive%\inetpub\Logs\FailedReqLogFiles\
. You can open this log by using Internet Explorer, and it will be rendered as an HTML document that can be easily browsed. Following is an example of the URL rewrite specific events that can be found in the trace log file:
These events show how the rewrite rules were evaluated and how requested URL was modified by rewrite module. Let's walk through some of the events to better understand the rule evaluation logic:
URL_REWRITE_START - This event indicates the start of the URL rewrite events. The event properties provide the following information:
- The input URL string is "/article/234/some-title".
- There was no query string.
- Scope="Distributed" indicates that rules are local (that is, the rules are defined in the Web.config for the site) as opposed to global (that is, defined on the server level).
RULE_EVALUATION_START - This event indicates the start of rule evaluation logic. The event properties provides the following information:
- Rule uses regular expressions for pattern syntax (patternSyntax="ECMAScript")
- Subsequent rules will be evaluated (StopProcessing = "false")
- The rule is defined on the site root level (RelativePath = "/")
PATTERN_MATCH - This event provides information on how URL was matched with the rule pattern. The event properties provide the following information:
- Rule pattern was "." (that is, matches any character)
- Input url matched the pattern successfully
CONDITIONS_EVALUATION_START - Since the input URL matched the pattern the conditions evaluation started
CONDITION_EVALUATION - This event provides the following information:
- The value of HTTP_HOST was "localhost" and it matched the pattern
- Since the condition negation was specified in the rule (i.e. Negated="true") the condition evaluation did not succeed.
CONDITIONS_EVALUATION_END - This event shows that evaluation of conditions for this rule did not succeed
RULE_EVALUATION_END - This event shows that the rule did not modify the URL (Succeeded="false"). This is because rule condition evaluation failed.
RULE_EVALUATION_START - This even shows that URL string was passed to the second rule
PATTERN_MATCH - This event provides information on how URL was matched with the rule pattern. The event properties tell us that:
- The rule pattern was: "^article/([0-9]+)/([0-9a-z]+)"
- The input URL matched the pattern successfully
REWRITE_ACTION - This event indicates that the rule evaluation succeeded and the URL was rewritten to "/article.aspx" with query string "id=234&title=some-title"
Summary
URL rewrite specific events logged by FRT provide very detailed information that can be used for troubleshooting and debugging of URL rewrite rules as well as just for understanding how rules evaluation logic is applied to a URL string.