Using Failed Request Tracing to Trace Rewrite Rules

by Ruslan Yakushev

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:

  1. IIS 7.0 or above with ASP.NET and "Tracing" role services enabled
  2. 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.

Screenshot of accessing the article page through the web 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}&amp;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 format http://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:

Screenshot of the U R L Rewrite Module Test Page that displays the original U R L and the rewritten version.

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:

  1. Click on "Failed Request Tracing Rules" icon to get to the list of FRT rules.
    Screenshot of the Default Web Site Home pane with Failed Request Tracing Rules selected.
  2. Click on the "Add …" action to bring up the FRT rule creation wizard.Screenshot of the Add Failed Request Tracing Rule dialog with All content (asterisk) selected.
  3. On first page of the wizard choose "All content (*)"
  4. Click "Next" and specify the status code(s) as "200-399"
    Screenshot of setting the status codes to the value of 200 dash 399.
  5. Click Next and then uncheck all the trace providers except "WWW Server" and then uncheck all the provider areas except "Rewrite"Screenshot of setting Providers to only W W W Server and Areas to only Rewrite.
  6. 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:

Screenshot of accessing an F R T log using a web browser. The log shows the list of rewrite rules and their rewrite logic.

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.