Adding Trace Failed Requests <add>

Overview

Each <add> element in the <traceFailedRequests> collection can include a <traceAreas> element that defines the tracing providers and the provider-specific areas that will generate tracing events for the current tracing rule. It can also contain a <failureDefinition> element, which you can use to configure the failure conditions for a request, including the amount of time it takes for the server to respond, the HTTP status code, and the amount of information included in the trace.

Compatibility

Version Notes
IIS 7.5 The <add> element was not modified in IIS 7.5.
IIS 7.0 The <add> element of the <traceFailedRequests> collection was introduced in IIS 7.0.
IIS 6.0 N/A

Setup

After you finish the default installation of IIS 7, you must install the tracing role service to use failed request tracing. After you install the role service, you still must enable failed request tracing at the site level, application level, or directory level.

Windows Server 2008 or Windows Server 2008 R2

  1. On the taskbar, click Start, point to Administrative Tools, and then click Server Manager.
  2. In the Server Manager hierarchy pane, expand Roles, and then click Web Server (IIS).
  3. In the Web Server (IIS) pane, scroll to the Role Services section, and then click Add Role Services.
  4. On the Select Role Services page of the Add Role Services Wizard, select Tracing, and then click Next.

  5. On the Confirm Installation Selections page, click Install.
  6. On the Results page, click Close.

Windows Vista or Windows 7

  1. On the taskbar, click Start, and then click Control Panel.
  2. In Control Panel, click Programs and Features, and then click Turn Windows Features on or off.
  3. Expand Internet Information Services, then World Wide Web Services, then Health and Diagnostics.
  4. Select Tracing, and then click OK.

How To

How to enable tracing

  1. Open Internet Information Services (IIS) Manager:
    • If you are using Windows Server 2008 or Windows Server 2008 R2:
      • On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
    • If you are using Windows Vista or Windows 7:
      • On the taskbar, click Start, and then click Control Panel.
      • Double-click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.
  2. In the Connections pane, select the server connection, site, application, or directory for which you want to configure failed request tracing.
  3. In the Actions pane, click Failed Request Tracing...

  4. In the Edit Web Site Failed Request Tracing Settings dialog box, select the Enable check box to enable tracing, leave the default value or type a new directory where you want to store failed request log files in the Directory box, type the number of failed request trace files you want to store in the Maximum number of trace files box, and then click OK.

How to configure failure definitions

  1. Open Internet Information Services (IIS) Manager:
    • If you are using Windows Server 2008 or Windows Server 2008 R2:
      • On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
    • If you are using Windows Vista or Windows 7:
      • On the taskbar, click Start, and then click Control Panel.
      • Double-click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.
  2. In the Connections pane, go to the connection, site, application, or directory for which you want to configure failed request tracing.
  3. In the Home pane, double-click Failed Request Tracing Rules.

  4. In the Actions pane, click Add...
  5. On the Specify Content to Trace page of the Add Failed Request Tracing Rule Wizard, select the content type you want to trace, and then click Next.

  6. On the Define Trace Conditions page, select the conditions you want to trace, and then click Next. Trace conditions can include any combination of status codes, a time limit that a request should take, or the event severity. If you specify all conditions, the first condition that is met generates the failed request trace log file.

  7. On the Select Trace Providers page, select one or more of the trace providers under Providers.

  8. On the Select Trace Providers page, select one or more of the verbosity levels under Verbosity.

  9. If you selected the ASPNET or WWW Server trace provider in step 8, select one or more functional areas for the provider to trace under Areas of the Select Trace Providers page.
  10. Click Finish.

Configuration

Attributes

Attribute Description
customActionExe Optional string attribute.

Specifies an executable file to run when a failure condition is reached (for example, to run a VBScript file, specify "Cscript.exe"). All command-line variables will be expanded. For example, "%windir%" will be expanded to the path of the Windows directory.
customActionParams Optional string attribute.

Contains parameters to pass to the executable file specified in the customActionExe attribute. Command-line variables such as "%windir%" will be expanded. You may also use parameter variables such as "%1" and "%2" in the string that you specify (for example, "MyScript.vbs %1 %2").
customActionTriggerLimit Optional uint attribute.

Specifies the maximum number of times the program specified by the customActionExe attribute will execute during the lifetime of the worker process for the failed-request definition. This value resets every time that the worker process recycles. Permissible values are from 0 through 10000. This feature can be used, for example, to create a memory dump after the next failure but not after subsequent failures.

Note: If the CustomActionTriggerLimit value that you specify is reached during the run time of the worker process, subsequent failed requests will be logged, but the program specified in CustomActionExe will not run. The entries in the failed-requests log will indicate that the CustomActionTriggerLimit value has been reached.

The default is 1.

path Required string attribute.

Specifies the path for which you want to log trace events. The path is relative to the URL (virtual directory/directory). Sub paths cannot be used. In addition, the path must be local to the directory where the definition is set. Wildcard values can be used, for example, "*.aspx". For tracing the default document, use "/" as the path value.

Child Elements

Element Description
traceAreas Required element.

Configures what to trace for a given path.
failureDefinitions Required element.

Defines the conditions in which to save traces for a request.

Configuration Sample

The following configuration example configures tracing at the server level in the ApplicationHost.config file. It sets tracing for all .aspx files, uses the <traceAreas> element to set the ASPNET provider and trace against all ASP.NET areas, which are Infrastructure, Module, Page and AppServices. The sample also uses the verbosity attribute to set the amount of information returned to the tracing file to warning. Lastly, the sample uses the <failureDefinitions> element to trace only requests that generate a HTTP 404 status code.

<tracing>
   <traceFailedRequests>
      <add path="*.aspx">
         <traceAreas>
            <add provider="ASPNET" areas="Infrastructure,Module,Page,AppServices" verbosity="Warning" />
         </traceAreas>
         <failureDefinitions statusCodes="404" />
      </add>
   </traceFailedRequests>
</tracing>

Sample Code

The following examples enable verbose failed request tracing for HTTP 500 errors in ASP.NET content on all requests to *.aspx pages.

AppCmd.exe

appcmd.exe set config "Contoso" -section:system.webServer/tracing/traceFailedRequests /+"[path='*.aspx']" 

appcmd.exe set config "Contoso" -section:system.webServer/tracing/traceFailedRequests /+"[path='*.aspx'].traceAreas.[provider='ASPNET',areas='Infrastructure,Module,Page,AppServices',verbosity='Verbose']" 

appcmd.exe set config "Contoso" -section:system.webServer/tracing/traceFailedRequests /[path='*.aspx'].failureDefinitions.statusCodes:"500" 

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample
{
   private static void Main()
   {
      using (ServerManager serverManager = new ServerManager())
      {
         Configuration config = serverManager.GetWebConfiguration("Contoso");
         ConfigurationSection traceFailedRequestsSection = config.GetSection("system.webServer/tracing/traceFailedRequests");
         ConfigurationElementCollection traceFailedRequestsCollection = traceFailedRequestsSection.GetCollection();

         ConfigurationElement addElement = traceFailedRequestsCollection.CreateElement("add");
         addElement["path"] = @"*.aspx";

         ConfigurationElementCollection traceAreasCollection = addElement.GetCollection("traceAreas");
         ConfigurationElement addElement1 = traceAreasCollection.CreateElement("add");
         addElement1["provider"] = @"ASPNET";
         addElement1["areas"] = @"Infrastructure,Module,Page,AppServices";
         addElement1["verbosity"] = @"Verbose";
         traceAreasCollection.Add(addElement1);

         ConfigurationElement failureDefinitionsElement = addElement.GetChildElement("failureDefinitions");
         failureDefinitionsElement["statusCodes"] = @"500";
         traceFailedRequestsCollection.Add(addElement);

         serverManager.CommitChanges();
      }
   }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration

Module Sample
   Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetWebConfiguration("Contoso")
      Dim traceFailedRequestsSection As ConfigurationSection = config.GetSection("system.webServer/tracing/traceFailedRequests")
      Dim traceFailedRequestsCollection As ConfigurationElementCollection = traceFailedRequestsSection.GetCollection

      Dim addElement As ConfigurationElement = traceFailedRequestsCollection.CreateElement("add")
      addElement("path") = "*.aspx"
      Dim traceAreasCollection As ConfigurationElementCollection = addElement.GetCollection("traceAreas")
      Dim addElement1 As ConfigurationElement = traceAreasCollection.CreateElement("add")
      addElement1("provider") = "ASPNET"
      addElement1("areas") = "Infrastructure,Module,Page,AppServices"
      addElement1("verbosity") = "Verbose"
      traceAreasCollection.Add(addElement1)

      Dim failureDefinitionsElement As ConfigurationElement = addElement.GetChildElement("failureDefinitions")
      failureDefinitionsElement("statusCodes") = "500"
      traceFailedRequestsCollection.Add(addElement)

      serverManager.CommitChanges()
   End Sub
End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Contoso";
var traceFailedRequestsSection = adminManager.GetAdminSection("system.webServer/tracing/traceFailedRequests", "MACHINE/WEBROOT/APPHOST/Contoso");
var traceFailedRequestsCollection = traceFailedRequestsSection.Collection;

var addElement = traceFailedRequestsCollection.CreateNewElement("add");
addElement.Properties.Item("path").Value = "*.aspx";
var traceAreasCollection = addElement.ChildElements.Item("traceAreas").Collection;

var addElement1 = traceAreasCollection.CreateNewElement("add");
addElement1.Properties.Item("provider").Value = "ASPNET";
addElement1.Properties.Item("areas").Value = "Infrastructure,Module,Page,AppServices";
addElement1.Properties.Item("verbosity").Value = "Verbose";
traceAreasCollection.AddElement(addElement1);

var failureDefinitionsElement = addElement.ChildElements.Item("failureDefinitions");
failureDefinitionsElement.Properties.Item("statusCodes").Value = "500";
traceFailedRequestsCollection.AddElement(addElement);

adminManager.CommitChanges();

VBScript

Set adminManager = createObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Contoso"
Set traceFailedRequestsSection = adminManager.GetAdminSection("system.webServer/tracing/traceFailedRequests", "MACHINE/WEBROOT/APPHOST/Contoso")
Set traceFailedRequestsCollection = traceFailedRequestsSection.Collection

Set addElement = traceFailedRequestsCollection.CreateNewElement("add")
addElement.Properties.Item("path").Value = "*.aspx"
Set traceAreasCollection = addElement.ChildElements.Item("traceAreas").Collection

Set addElement1 = traceAreasCollection.CreateNewElement("add")
addElement1.Properties.Item("provider").Value = "ASPNET"
addElement1.Properties.Item("areas").Value = "Infrastructure,Module,Page,AppServices"
addElement1.Properties.Item("verbosity").Value = "Verbose"
traceAreasCollection.AddElement addElement1

Set failureDefinitionsElement = addElement.ChildElements.Item("failureDefinitions")
failureDefinitionsElement.Properties.Item("statusCodes").Value = "500"
traceFailedRequestsCollection.AddElement addElement

adminManager.CommitChanges()
Deprecated Elements