IIS 7.0 : Using Command Line Tools - Working with Failed Request Tracing

The Trace object in Appcmd provides a convenient way to enable and use the Failed Request Tracing (FRT) feature in IIS 7.0 to diagnose server problems.

You can use the Trace object to do the following:

• Turn FRT on and off for each Web site

• Manage FRT tracing rules for any URL

• Search for and inspect FRT log files

Turning on Failed Request Tracing

To turn on FRT for a particular URL, you must first enable the feature for the Web site. You can do this with Appcmd by using the Configure Trace command.

appcmd configure trace SiteName /enablesite

The /enablesite parameter enables the use of FRT for the site specified by the SiteName identifier (this identifier can also be a URL, in which case Appcmd will turn on tracing for the corresponding site). For example, to enable FRT for the "Default Web Site" site, use the following syntax.

appcmd configure trace "Default Web Site" /enablesite

Note

Be sure to disable FRT when not using it with the /disablesite parameter.

You can also use the /disablesite parameter to turn off FRT for the Web site when you are not using it. Doing so allows you to leave the Failed Request Tracing rules configured for URLs on the site and simply toggle tracing on or off at the Web site level.

Creating Failed Request Tracing Rules

To produce FRT trace logs, you need to create rules that indicate the failure conditions that trigger the trace to be logged, as well as which trace events should be captured. To do this, you use the /enable parameter of the Configure Trace command. This has the following syntax.

appcmd Configure Trace <URL> /enable [/path:string] [/areas:string]
[/verbosity:level] [/timetaken:timespan] [/statuscodes:string]

This command supports the parameters listed in Table 1.

Table 1. Parameters of the Configure Trace Command

Parameter	Description
path	The URL path for which the rule is enabled. This can be an extension in the form of "*.extension" or "*" to indicate all requests. If not specified, defaults to "*".
areas	The list of providers and their areas to trace. This is in the form of "provider/area1,area2:verbosity,...", where the area list and verbosity are optional for each provider entry. If not specified, this uses all registered providers and their subareas at "Verbose" verbosity level.
verbosity	The verbosity level of an event that causes the request to meet the failure definition and generate the trace log. You can use this to generate trace logs if an event of Warning or Error verbosity is encountered. Allowed values are Ignore, CriticalError, Error, and Warning. If not specified, the default is Warning.
timetaken	The execution time (in time span format) that causes the request to meet the failure definition and generate the trace log. You can use this parameter to generate trace logs only if the request exceeds the specified execution time, to capture slow or hung requests. If not specified, defaults to one minute.
statuscodes	Response status codes that cause the request to meet the failure definition and generate the trace log. This is in the form of "status.substatus,...", where substatus is optional. You can use this to generate the trace log for requests that fail with specific error response codes. If not specified, defaults to "500,400,401,403".

When you use the /enable command without specifying the /path parameter, it creates an entry that matches all requests to the URL with path set to "*". For example, we can use the following syntax to quickly enable FRT tracing using all default configurations.

appcmd configure trace "Default Web Site/" /enable

This generates the following configuration for the system.webServer/tracing/traceFailedRequests configuration section.

        <tracing>
            <traceFailedRequests>
                <add path="*.aspx">
                    <traceAreas>
                        <add provider="ASPNET"
areas="Infrastructure,Module,Page,AppServices" />
                    </traceAreas>
                    <failureDefinitions statusCodes="404" />
                </add>
                <add path="*">
                    <traceAreas>
                        <add provider="WWW Server"
areas="Authentication,Security,Filter,StaticFile,CGI,Compression,Cache,RequestNotifications,
Module" verbosity="Verbose" />
                        <add provider="ASP" areas="" verbosity="Verbose" />
                        <add provider="ISAPI Extension" areas=""
verbosity="Verbose" />
                        <add provider="ASPNET"
areas="Infrastructure,Module,Page,AppServices" verbosity="Verbose" />
                    </traceAreas>
                    <failureDefinitions timeTaken="00:01:00"
statusCodes="500,400,401,403" verbosity="Warning" />
                </add>
            </traceFailedRequests>
        </tracing>

Note that the rule uses a path of "*" to apply to all requests at or below the URL at which the configuration is set, specifies all the registered trace providers and areas with the Verbose verbosity level, and specifies the default failure definition triggers.

You can specify the /path parameter to create additional rules for specific extensions, for example, to enable tracing for ASPX pages only.

appcmd configure trace "Default Web Site/" /enable /path:*.aspx

You can use the /disable parameter instead of /enable to remove the rules, specifying the /path parameter to indicate which rule you’d like to remove. If you omit the /path parameter, the tool will attempt to remove the rule with a path of "*".

Additionally, you can override both the list of trace providers and areas that are being captured by each rule—as well as the failure definition for the rule—by using the optional parameters listed in Table 1. For example, to configure an FRT trace rule that intercepts only the events from the ASP.NET provider and only generates log files for the 404 status code, you can use the following syntax.

appcmd configure trace "Default Web Site/" /enable /path:*.aspx
/areas:ASPNET/Infrastructure,Module,Page,AppServices /statuscodes:404

Searching Failed Request Tracing logs

Besides enabling and configuring Failed Request Tracing rules, Appcmd also provides a convenient ability to search the trace log files. You can use this to quickly find the trace log, and even the event inside of the log, to help you with diagnosing a particular problem.

You can search the existing trace log files by using the List Trace command. This command has the following syntax.

appcmd list traces [identifier] [/url:string] [/site.name:string] [apppool.name:string]
[/statuscode:string] ...

This command accepts the parameters listed in Table 2.

Table 2. Parameters of the List Trace Command

Parameter	Description
identifier	The unique identifier of each trace log, which is in the form of "SiteName/logfilename.xml". You can use this to look up a specific trace log.
url	The URL of the request. Appcmd supports partial URLs by default, doing a prefix match on a normalized version of the URL.
site.name	The name of the Web site for which to show the request logs. Using this can improve the efficiency of the command because only the logs for the specified Web site are retrieved.
apppool.name	The name of the application pool for which to show the request logs.
statuscode	The status code for the request.

In addition, you can specify other attributes of the trace object to filter the results on. To see the available attributes, list the trace logs with a "/text:*" parameter. For example, to list all trace logs for a particular Web site, use the following syntax.

appcmd list traces /site.name:"Default Web Site"

To list all trace logs for a particular URL, use the following syntax.

appcmd list traces /site.name:"Default Web Site"
/url:http://localhost/myapp/test.html

The output of the command contains the trace log objects, as in the following example, and includes the trace log identifier, the URL of the request, the status code, and the worker process.

TRACE "Default Web Site/fr000021.xml"
(url:http://localhost:80/myapp/test.html,statuscode:200,wp:3284)
TRACE "Default Web Site/fr000022.xml"
(url:http://localhost:80/,statuscode:200,wp:3284)

When displayed in the "/text:*" mode, each trace log also has many additional attributes (which you can also use to filter the resulting output when you use the List Traces command).

TRACELOG
  TRACE.NAME:"Default Web Site/fr000022.xml"
  PATH:"C:\inetpub\logs\FailedReqLogFiles\W3SVC1\fr000022.xml"
  URL:"http://localhost:80/myapp/test.html"
  STATUSCODE:"200"
  SITE.ID:"1"
  SITE.NAME:"Default Web Site"
  WP.NAME:"3284"
  APPPOOL.NAME:"DefaultAppPool"
  verb:"GET"
  remoteUserName:"Administrator"
  userName:"Administrator"
  tokenUserName:"contoso\Administrator"
  authenticationType:"Basic"
  activityId:"{00000000-0000-0000-0300-0080010000FD}"
  failureReason:"STATUS_CODE"
  triggerStatusCode:"200"

Note that the log provides additional information about the request, including the authentication type and the reason the request failed. It also includes the physical path to the log file so that you can open the associated log file in a browser, using the FRT style sheet for more in-depth diagnostics.

Finally, you can inspect the trace log file to peer into actual events, to quickly locate the events that caused a particular request to fail. To do this, you can use the Inspect Trace command. This command has the following syntax.

appcmd inspect trace <identifier> [/event.name:string]
[/name:string] [/level:int] [/providerid:string]

This command supports the parameters in Table 3.

Table 3. Parameters for the Inspect Trace Command

Parameter	Description
identifier	The trace log identifier. This is required.
event.name	The unique identifier of the event in this trace log. This is in the form of tracelogidentifier#index, as in "Default Web Site/fr000001.xml#174". You can use this identifier id to look up a specific event in the trace log.
name	The friendly name of the event. Use this to filter for specific events.
level	The numeric verbosity level of each event. Use this to filter for events with specific verbosity, such as Warning, Error, or CriticalError.
providerid	The globally unique identifier (GUID) of the provider that generated this event.

In addition, you can specify other trace object attributes to filter the results on. To see the available attributes, inspect a trace log with a "/text:*" parameter.

You can use the Inspect Trace command to quickly find the event that indicates the desired error condition. For example, to show all events in the trace log that have a Warning or above verbosity level, use the following syntax.

appcmd list traces "Default Web Site/fr000001.xml" "/level:$>4"

To look for a specific event, use the following syntax.

appcmd list traces "Default Web Site/fr000001.xml"
"/name:WARNING_ _SEND_CUSTOM_ERROR"

You can combine these simple techniques with command pipelining to quickly analyze multiple trace log files.