Create a Tracing Rule for Failed Requests (IIS 7)

  • Article

Applies To: Windows 7, Windows Server 2008, Windows Server 2008 R2, Windows Vista

If a request to a server fails or takes too long, you can define a failed request tracing rule that will capture trace events for that request and log these trace events, as they occur, without having to reproduce the error. Events are written to the trace log only if the request exceeds the time interval allocated for the request to complete processing, or if the specified HTTP status and sub status code combination is generated for the response. The trace log only contains information specific to that failed request. You no longer must look through large log files that contain every request to find the information that you need about a specific failed request.

Note

You must enable trace logging before a trace log will be created for a failed request. For more information about how to enable trace logging, see Enable Trace Logging for Failed Requests (IIS 7).

Note

Adding a configuration setting adds the setting at the local level and to any child levels that inherit the setting.

Prerequisites

For information about the levels at which you can perform this procedure, and the modules, handlers, and permissions that are required to perform this procedure, see Tracing for Failed Requests Feature Requirements (IIS 7).

Exceptions to feature requirements

  • None

To create a tracing rule for failed requests

You can perform this procedure by using the user interface (UI), by running Appcmd.exe commands in a command-line window, by editing configuration files directly, or by writing WMI scripts.

User Interface

To Use the UI

  1. Open IIS Manager and navigate to the level you want to manage. For information about opening IIS Manager, see Open IIS Manager (IIS 7). For information about navigating to locations in the UI, see Navigation in IIS Manager (IIS 7).

  2. In Features View, double-click Failed Request Tracing Rules.

  3. On the Failed Request Tracing Rules page, click Add in the Actions pane.

  4. In the Specify Content to Trace area of the Add Failed Request Tracing Rule dialog box, select:

    • All content (*) - when you want to track all files in a directory.

    • ASP.NET (*.aspx) - when you want to track all .aspx files in a directory.

    • ASP (*.asp) - when you want to track all .asp files in a directory.

    • Custom - when you want to define a failure for a custom set of content, such as "xyz.exe" or "*.jpg". This can contain, at most, one wildcard and must be local to the directory where the failed request definition is set.

  5. Click Next.

  6. In the Define Trace Conditions area of the Add Failed Request Tracing Rule dialog box, select one or more of the following conditions to trace:

    • Status code(s) - enter the status code(s) you want to trace. You can enter multiple status codes in this list by using commas to separate each code. You can also refine your status codes using sub status codes, such as "404.2, 500."

    • Time taken - enter the maximum time, in seconds, that a request should take.

    • Event severity - select the severity level you want to trace from the Event severity drop-down list. You can select Error, Critical Error, or Warning.

Note

If all conditions are specified, the first condition that is met will generate the failed request trace log file.

  1. Click Next.

  2. In the Select Trace Providers area of the Add Failed Request Tracing Rule dialog box, under Providers select one or more of the following trace providers:

    • ASP - when you want to trace the start and completion of the execution of an ASP request.

    • ASPNET - when you want to see transitions into and out of managed code. This includes *.aspx requests.

    • ISAPI Extension - when you want to trace the transition of a request into and out of an ISAPI extension process.

    • WWW Server - when you want to trace requests through the IIS worker process.

  3. In the Select Trace Providers area of the Add Failed Request Tracing Rule dialog box, under Verbosity select one or more of the following verbosity levels:

    • General - provides information that gives context for the request activity, for example, a GENERAL_REQUEST_START event that logs the URL and the verb for the request.

    • Critical Errors - provides information about actions that can cause a process to exit or that are about to cause a process to exit.

    • Errors - provides information about components that experience an error and cannot continue to process requests. These errors usually indicate a server-side problem.

    • Warnings - provides information about components that experience an error but can continue to process the request.

    • Information - provides general information about requests.

    • Verbose - provides detailed information about requests. This is the default selection.

  4. If you selected the ASPNET trace provider in step 8, in the Select Trace Providers area of the Add Failed Request Tracing Rule dialog box, under Areas select one or more of the following functional areas for the provider to trace:

    • Infrastructure - when you want to trace events that are primarily related to entering and leaving various parts of the ASP.NET infrastructure.

    • Module - when you want to trace events that are logged as a request enters and leaves various HTTP pipeline modules.

    • Page - when you want to generate trace events that correspond to the execution of specific ASP.NET page-related events, such as Page_Load, and so on.

    • AppServices - when you want to trace events that are logged as part of the new application services functionality.

  5. If you selected the WWW Server trace provider in step 8, in the Select Trace Providers area of the Add Failed Request Tracing Rule dialog box, under Areas select one or more of the following functional areas for the provider to trace:

    • Authentication - when you want to trace authentication attempts, for example: the name of the authenticated user, the authentication scheme (anonymous, basic, etc.), and the results of the authentication attempt (successful, failed, error, and so on).

    • Security - when you want to generate trace events when requests are rejected by the IIS server for security-related reasons, for example, if a client request was denied access to a resource.

    • Filter - when you want to determine how long it takes an ISAPI filter to process requests.

    • StaticFile - when you want to trace how long it takes requests for static files to be completed.

    • CGI - when you want to generate trace events when a request is for a CGI file.

    • Compression - when you want to generate trace events when a response is compressed.

    • Cache - when you want to generate trace events for cache operations associated with the request.

    • RequestNotifications - when you want to capture all request notifications, both on entrance and on exit.

    • Module - when you want to trace events that are logged when a request enters and leaves various HTTP pipeline modules, or to capture trace events for managed modules.

  6. Click Finish.

Command-line

Create a tracing rule for failed requests

To create a tracing rule for failed requests, use the following syntax:

appcmd configure trace "URL" /enable /path:*|*.aspx|*.asp|custom **/statuscodes:**int **/timeTaken:**timeSpan /areas:ASP;|ASPNET/Infrastructure|Module|Page|AppServices;|ISAPI;|WWW Server/Authentication|Security|Filter|StaticFile|CGI|Compression|Cache|RequestNotifications|IISGeneral|All /verbosity:General|Critical Errors|Errors|Warnings|Information|Verbose

The variable URL is the Uniform Resource Locator (URL) for the file that you want to trace. The variable path *|*.aspx|*.asp|custom sets the content you want to trace. Separate multiple content types with a comma (,). The variable statuscodes int is the HTTP status code(s) you want to trace. Separate multiple status codes with a comma (,). The variable timeTaken timeSpan is the maximum time, in seconds (hh:mm:ss) that a request should take. The variable areas ASP;|ASPNET/Infrastructure|Module|Page|AppServices;|ISAPI;|WWW configures the trace providers and functional areas for the provider to trace. Separate multiple trace providers with a semicolon (;) and separate multiple functional areas with a comma (,). The variable verbosity General|Critical Errors|Errors|Warnings|Information|Verbose sets the type and amount of information that you want the log file to contain. The default value is Verbose.

For example, to create a failed request tracing rule that logs requests to an ASP.NET file that takes longer than 20 seconds to respond, type the following at the command prompt, and then press ENTER:

Appcmd configure trace "Contoso/catalog.aspx" /enable /path:*.aspx /timeTaken:00:00:20 /areas:ASPNET/Infrastructure,Module,Page,Appservices /verbosity:Warning

For more information about Appcmd.exe, see Appcmd.exe (IIS 7).

Configuration

The procedure in this topic affects the following configuration elements:

  • <traceFailedRequests>

  • <traceAreas>

  • <failureDefinitions>

For more information about IIS 7 configuration, see IIS 7.0: IIS Settings Schema on MSDN.

WMI

Use the following WMI classes, methods, or properties to perform this procedure:

  • TraceFailedRequestsSection.Add method

For more information about WMI and IIS, see Windows Management Instrumentation (WMI) in IIS 7. For more information about the classes, methods, or properties associated with this procedure, see the IIS WMI Provider Reference on the MSDN site.

See Also

Concepts

Configuring Tracing for Failed Requests in IIS 7