Enabling and Configuring FRT
To
turn on tracing with FRT, you must enable FRT for each Web site you
want to monitor and configure the FRT rules for the Web site or
particular URL you’d like to trace. (Note that you must enable/disable
FRT at the site level, but you can configure the failure definitions on any
URL within that site. Similarly, if you don’t have FRT enabled for a
site, there’s nothing preventing you from creating failure
definitions—they just won’t execute until you turn FRT on at the site
level.) To enable FRT for a Web site, in IIS Manager, select the site
you want to monitor in the tree. In the Actions pane on the right side
of IIS Manager, click Failed Request Tracing. In the Edit Web Site
Failed Request Tracing Settings dialog box, select the Enable check box,
as shown in Figure 1.
For each Web site, you can specify an alternate location for the site’s
FRT log files. (By default, the log files are collected in the %SystemDrive%\Inetpub\Logs\FailedReqLogFiles
folder. Whenever possible, you should specify a location other than on
the system drive.) You can also configure the maximum number of log
files to keep, which is important because FRT will create one log file
per failure. If there are a lot of failures, the Maximum Number Of Trace
Files option limits the number of failures retained on the file system.
You
can delegate FRT settings to allow application developers who are not
server administrators to use FRT within their own applications.
Tracing a Specific Error Code
As an example, imagine
you need to troubleshoot problems occurring with security access to a
Web site. To configure FRT so that you can thoroughly examine all the
system responses when a client receives a 401.3 Access Is Denied error
code, perform the following procedure:
1. | In IIS Manager, select the Web site for which you want to configure tracing in the tree.
| 2. | Double-click Failed Request Tracing Rules.
Note Make sure the Features View option is selected at the bottom of the center pane. |
| 3. | In the Actions pane, click the Add link, as shown here.
 | 4. | In
the Specify Content To Trace page of the Add Failed Request Tracing
Rule Wizard, you can specify the type of content you want to trace. For
this procedure, specify All Content, as shown here, and click Next.
 | 5. | The
Define Trace Conditions page lets you specify what you consider to be a
failed request. You can define a failed request as any combination of
returned status codes, response time, or event severity. If you do
define multiple conditions, the first one encountered will trigger the
log. To define a
failed request as a request that returns an Access Is Denied error code,
type 401.3 in the Status Code(s)
text box, as shown here, and click Next. (Note that in general, if you
aren’t sure of the exact error that is occurring, you typically would
not specify the substatus code.)
 | 6. | In
the Select Trace Providers page, you tell IIS 7.0 what you want to
trace when a request fails, as well as the level of detail to include in
the trace. As shown in the following image, deselect all check boxes in
the Providers list except the WWW Server provider; select Verbose in
the Verbosity drop-down list; in the Areas list, clear all check boxes
except Authentication, Security, RequestNotifications, and Module. (You
must scroll down to see the Module check box.) Refer to Table 1 for information about the areas you can specify for the WWW Server provider. Click Finish to add the rule for the Web site.
Table 1. Trace Areas for the WWW Server Provider| Area | Description |
|---|
| Authentication | Traces authentication-related events | | Security | Traces
security-related events, including authorization and access control
list (ACL) checks that IIS performs on files and other resources | | Filter | Traces
filter events as a request goes into and comes out of various Internet
Server Application Programming Interface (ISAPI) filters configured for
the URL being traced | | StaticFile | Traces static file events, including whether or not the file was accessed from cache | | CGI | Traces events generated by the Common Gateway Interface (CGI) module, including FastCGI requests | | Compression | Traces events raised as they relate to the compressing of responses and serving compressed responses | | Cache | Traces cache operations for a request | | RequestNotifications | Traces all request pipeline notifications to modules | | Module | Traces events that are logged when each module begins and each module ends processing a request notification for an event |
 |
To
test your FRT settings and generate an FRT trace for the example set up
in the preceding steps, you can simply restrict security permissions
for a resource on the Web site and then try to browse that resource
using Microsoft Internet Explorer. The browser will report a 401.3
error, as shown in Figure 2, and FRT will generate a trace log.
|
Failure Request
Tracing for IIS 7.0 can trigger failures on three key conditions:
Status/Substatus codes, Time Taken, and Event Verbosity. One thing to
remember is that the trigger overall is a logical OR of all the failure
conditions defined. If you define all three conditions, say statusCodes=“400-599”, timeTaken=“00:00:10”, and verbosity=“Error”, the worker process will flush the trace log for the failed request upon reaching the first
of those conditions. If your request eventually errors out with an HTTP
status code of 500, but it takes 30 seconds to do that, you’ll actually
trigger on the timeTaken value. The attribute <failedRequest failureReason=“<reason>”> in the trace log will tell you exactly what failure condition triggered the flush.
The events that make it into the trace log are those that are raised up to the point of the failure. What this means is that only status/substatus code failure conditions (failureReason=“STATUS_CODE”) will capture the entire request from start to end. For timeTaken triggers, you’ll see all the events received up to the time limit.
In the example from the previous paragraph, a 10-second failure
condition will result in IIS capturing the events up to that 10-second
limit, and no more. The same thing goes for verbosity triggers—when we
receive the first event whose verbosity is equal to or more severe than
the trigger condition, we’ll flush all events received up to that point
(including the trigger event).
So let’s say
your trigger condition wants to flush for Foobar.aspx with verbosity
level set to WARNING. Because verbosity levels that the server reports
are inclusive of the lesser error levels, IIS will flush the log for
Foobar.aspx when it receives the first
trace event for a request to that URL whose verbosity level is WARNING,
ERROR, or CRITICAL ERROR. Or if the failure condition’s verbosity level
is set to ERROR, IIS will flush upon receiving the first ERROR or
CRITICAL ERROR trace event.
The goal here is to
give you a flexible means of defining failure conditions and flush when a
certain condition is reached. Status code and time taken are currently
used most often, but verbosity is also helpful when you want to capture
application failures that result in customized 200 OKs to the client
that say “Sorry, cannot connect to product database.” Put an ERROR trace
event in your code and configure the verbosity failure condition to
capture these logs to help diagnose such failures!
Eric Deily
Senior Program Manager Lead
|
|
