HTTP Tracing <httpTracing>

Overview

The <httpTracing> element allows you to configure selective request-based event tracing for incoming IIS requests. <httpTracing> contains a <traceUrls> element, which contains a collection of <add> elements. Each <add> element defines a unique URL to enable tracing.

Note

Event Tracing for Windows (ETW) is a general-purpose, high-speed tracing facility provided by the operating system. Using a buffering and logging mechanism implemented in the kernel, ETW provides a tracing mechanism for events raised by both user-mode applications and kernel-mode device drivers. Additionally, ETW gives you the ability to enable and disable logging dynamically, making it easy to perform detailed tracing in production environments without requiring reboots or application restarts. The logging mechanism uses per-processor buffers that are written to disk by an asynchronous writer thread. This allows large-scale server applications to write events with minimum disturbance.

Note

To enable IIS request-based ETW, install the TracingModule.

By default, IIS emits request-based ETW events for all URLs through the provider IIS: WWW Server with GUID {3A2A4E84-4C21-4981-AE10-3FDA0D9B0F83} (the detailed information can be found in the <traceProviderDefinitions> element). To enable the URL filter for ETW specified by the <traceUrls> collection under the <httpTracing> element, the first (least significant) bit of the trace flags must be set as 1 when running an ETW session. For example, to enable IIS request-based ETW events ONLY for the URLs configured in the <traceUrls> collection, set the trace flags to 0xFFFFFFFF for an ETW session with the provider IIS: WWW Server. Such trace flags enable the URL filter as well as all trace areas. To enable the same events for all URLs, set the trace flags to 0xFFFFFFE instead.

Note

The URL filter defined in the <traceUrls> collection under the <httpTracing> element only affects IIS request-based ETW and has no impact on failed request tracing.

Compatibility

Version	Notes
IIS 10.0	The <httpTracing> element was not modified in IIS 10.0.
IIS 8.5	The <httpTracing> element was not modified in IIS 8.5.
IIS 8.0	The <httpTracing> element was not modified in IIS 8.0.
IIS 7.5	The <httpTracing> element was not modified in IIS 7.5.
IIS 7.0	The <httpTracing> element was introduced in IIS 7.0.
IIS 6.0	N/A

Setup

The <httpTracing> element is included in the default installation of IIS 7.

How To

There is no user interface for the <httpTracing> element for IIS 7. For examples of how to access the <httpTracing> element programmatically, see the Code Samples section of this document.

Configuration

You can configure the <httpTracing> element at the server level in the ApplicationHost.config file, or at the site, application, or directory level in a Web.config file.

Attributes

None.

Child Elements

Element	Description
traceUrls	Optional element. Specifies the URL for which you want to enable request-based ETW tracing.

Configuration Sample

The following example will enable tracing for the sample home page that ships with IIS 7 when placed in a Web.config file in the root of the Default Web Site.

<configuration>
   <system.webServer>
      <httpTracing>
         <traceUrls>
            <add value="/iisstart.htm" />
         </traceUrls>
      </httpTracing>
   </system.webServer>
</configuration>

Sample Code

The following examples enable tracing for the sample home page that ships with IIS 7 on Web site named Contoso by adding an entry to the <traceUrls> collection for that site.

AppCmd.exe

appcmd.exe set config "Contoso" -section:system.webServer/httpTracing /+"traceUrls.[value='/iisstart.htm']" /commit:apphost

Note

You must be sure to set the commit parameter to apphost when you use AppCmd.exe to configure these settings. This commits the configuration settings to the appropriate location section in the ApplicationHost.config file.

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.GetApplicationHostConfiguration();
         ConfigurationSection httpTracingSection = config.GetSection("system.webServer/httpTracing", "Contoso");
         ConfigurationElementCollection traceUrlsCollection = httpTracingSection.GetCollection("traceUrls");

         ConfigurationElement addElement = traceUrlsCollection.CreateElement("add");
         addElement["value"] = @"/iisstart.htm";
         traceUrlsCollection.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.GetApplicationHostConfiguration
      Dim httpTracingSection As ConfigurationSection = config.GetSection("system.webServer/httpTracing", "Contoso")

      Dim traceUrlsCollection As ConfigurationElementCollection = httpTracingSection.GetCollection("traceUrls")
      Dim addElement As ConfigurationElement = traceUrlsCollection.CreateElement("add")
      addElement("value") = "/iisstart.htm"
      traceUrlsCollection.Add(addElement)

      serverManager.CommitChanges()
   End Sub
End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";
var httpTracingSection = adminManager.GetAdminSection("system.webServer/httpTracing", "MACHINE/WEBROOT/APPHOST/Contoso");

var traceUrlsCollection = httpTracingSection.ChildElements.Item("traceUrls").Collection;
var addElement = traceUrlsCollection.CreateNewElement("add");
addElement.Properties.Item("value").Value = "/iisstart.htm";
traceUrlsCollection.AddElement(addElement);

adminManager.CommitChanges();

VBScript

Set adminManager = createObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"
Set httpTracingSection = adminManager.GetAdminSection("system.webServer/httpTracing", "MACHINE/WEBROOT/APPHOST/Contoso")

Set traceUrlsCollection = httpTracingSection.ChildElements.Item("traceUrls").Collection
Set addElement = traceUrlsCollection.CreateNewElement("add")
addElement.Properties.Item("value").Value = "/iisstart.htm"
traceUrlsCollection.AddElement addElement

adminManager.CommitChanges()