失败定义 <failureDefinitions>

  • 项目

概述

<failureDefinitions> 元素定义跟踪请求的条件。 失败条件包括状态代码、时间间隔或两者的组合。 此外，还可以指定跟踪的详细级别。

注意

添加其他详细选项会将 IIS 配置为在跟踪日志中返回更多信息，但详细日志可能会变得相当大。 如果日志文件超出了 <traceFailedRequestsLogging>元素的 maxLogFileSizeKB 属性定义的最大文件大小，则日志文件将在最大大小处截断，你需要增加该属性中指定的文件大小。

兼容性

版本 说明
IIS 10.0 为 IIS 10.0 中的 <failureDefinitions> 元素增加了 traceAllAfterTimeout 属性。
IIS 8.5 <failureDefinitions> 元素在 IIS 8.5 中未进行修改。
IIS 8.0 <failureDefinitions> 元素在 IIS 8.0 中未进行修改。
IIS 7.5 <failureDefinitions> 元素未在 IIS 7.5 中进行修改。
IIS 7.0 <failureDefinitions> 元素是在 IIS 7.0 中引入的。
IIS 6.0 空值

安装

完成 IIS 7 及更高版本的默认安装后，必须安装跟踪角色服务才能使用失败请求跟踪。 安装角色服务后，仍必须在站点级别、应用程序级别或目录级别启用失败请求跟踪。

Windows Server 2012 或 Windows Server 2012 R2

  1. 在任务栏上，单击 “服务器管理器”。
  2. 在“服务器管理器”中，单击“管理”菜单，然后单击“添加角色和功能”。
  3. 在“添加角色和功能”向导中，单击“下一步”。 选择安装类型，然后单击“下一步”。 选择目标服务器，然后单击“下一步”。
  4. 在“服务器角色”页上，依次展开“Web 服务器(IIS)”、“Web 服务器”和“运行状况和诊断”，然后选择“跟踪”。 单击 “下一步” 。
    Image of Health and Diagnostics pane in Server Roles page expanded with Tracing highlighted.。
  5. 在“选择功能”页上，单击“下一步”。
  6. 在“确认安装选择”页上，单击“安装”。
  7. 在“结果” 页面中单击“关闭” 。

Windows 8 或 Windows 8.1

  1. 在“开始”屏幕上，将指针一直移动到左下角，右键单击“开始”按钮，然后单击“控制面板”。
  2. 在“控制面板”中，单击“程序与功能”，然后单击“打开或关闭 Windows 功能”。
  3. 依次展开“Internet Information Services”、“万维网服务”、“运行状况和诊断”，然后选择“跟踪”。
    Image of World Wide Web Services and Health and Diagnostics pane expanded with Tracing selected.- 单击“确定”。
  4. 单击“关闭” 。

Windows Server 2008 或 Windows Server 2008 R2

  1. 在任务栏上，单击“开始”，指向“管理工具”，然后单击“服务器管理器”。
  2. 在“服务器管理器”层次结构窗格中，展开“角色”，然后单击“Web 服务器(IIS)”。
  3. 在“Web 服务器(IIS)”窗格中，滚动到“角色服务”部分，然后单击“添加角色服务”。
  4. 在“添加角色服务向导”的“选择角色服务”页上，选择“跟踪”，然后单击“下一步”。
    Screenshot of Health and Diagnostics pane in Add Role Services Wizard expanded with Tracing selected.
  5. 在“确认安装选择”页中，单击“安装”。
  6. 在“结果” 页面中单击“关闭” 。

Windows Vista 或 Windows 7

  1. 在任务栏上，单击“开始”，然后单击“控制面板”。
  2. 在“控制面板”中，单击“程序与功能”，然后单击“打开或关闭 Windows 功能”。
  3. 扩展“Internet Information Services”，展开“万维网服务”，然后展开“运行状况和诊断”。
  4. 选择“跟踪”，然后单击“确定”。
    Screenshot of World Wide Web Services and Health and Diagnostics pane expanded displaying Tracing selected.

操作方式

如何启用跟踪

  1. 打开 Internet Information Services (IIS) 管理器：

    • 如果使用的是 Windows Server 2012 或 Windows Server 2012 R2：

      • 在任务栏上，单击“服务器管理器”，单击“工具”，然后单击“Internet Information Services (IIS)管理器”。

    • 如果使用的是 Windows 8 或 Windows 8.1：

      • 按住 Windows 键，按字母 X，然后单击“控制面板”。
      • 单击“管理工具”，然后双击“Internet 信息服务(IIS)管理器”。

    • 如果使用的是 Windows Server 2008 或 Windows Server 2008 R2：

      • 在任务栏上，单击“开始”，指向“管理工具”，然后单击“Internet Information Services（IIS） 管理器”。

    • 如果使用的是 Windows Vista 或 Windows 7：

      • 在任务栏上，单击“开始”，然后单击“控制面板”。
      • 双击“管理工具”，然后双击“Internet 信息服务(IIS)管理器”。

  2. 在“连接”窗格中，选择要为其配置失败请求跟踪的服务器连接、站点、应用程序或目录。

  3. 在“操作”窗格中，单击“失败请求跟踪...”
    Image of Default Web Site Home page displaying I I S Manager console.

  4. 在“编辑网站失败请求跟踪设置”对话框中，选中“启用”复选框以启用跟踪，保留默认值或在“目录”框中键入要存储失败请求日志文件的新目录，键入要在“最大跟踪文件数”框中存储的失败请求跟踪文件数，然后单击“确定”。
    Image of Edit Web Site Failed Request Tracing Settings dialog box with command populating Directory field and Maximum number of trace files displayed.

如何配置失败定义

  1. 打开 Internet Information Services (IIS) 管理器：

    • 如果使用的是 Windows Server 2012 或 Windows Server 2012 R2：

      • 在任务栏上，单击“服务器管理器”，单击“工具”，然后单击“Internet Information Services (IIS)管理器”。

    • 如果使用的是 Windows 8 或 Windows 8.1：

      • 按住 Windows 键，按字母 X，然后单击“控制面板”。
      • 单击“管理工具”，然后双击“Internet 信息服务(IIS)管理器”。

    • 如果使用的是 Windows Server 2008 或 Windows Server 2008 R2：

      • 在任务栏上，单击“开始”，指向“管理工具”，然后单击“Internet Information Services（IIS） 管理器”。

    • 如果使用的是 Windows Vista 或 Windows 7：

      • 在任务栏上，单击“开始”，然后单击“控制面板”。
      • 双击“管理工具”，然后双击“Internet 信息服务(IIS)管理器”。

  2. 在“连接”窗格中，转到要为其配置失败请求跟踪的连接、站点、应用程序或目录。

  3. 在“开始”窗格中，双击“失败请求跟踪规则”。
    Screenshot of Home pane displaying I I S Manager console.

  4. 在“操作”窗格中，单击“添加...”。

  5. 在“添加失败请求跟踪规则”向导的“指定要跟踪的内容”页上，选择要跟踪的内容类型，然后单击“下一步”。
    Screenshot of Specify Content to Trace page showing All Content option selected.

  6. 在“定义跟踪条件”页上，选择要跟踪的条件，然后单击“下一页”。 跟踪条件可以包括状态代码、请求应采用的时间限制或事件严重性的任意组合。 如果指定所有条件，则满足的第一个条件将生成失败的请求跟踪日志文件。
    Image of Define Trace Conditions in Add Failed Request Tracing Rule Wizard.

  7. 在“选择跟踪提供程序”页上，选择“提供程序”下的一个或多个跟踪提供程序。
    Image of Select Trace Providers page with A S P and A S P NET selected as providers.

  8. 在“选择跟踪提供程序”页上，选择“详细程度”下的一个或多个详细级别。
    Screenshot of Select Trace Providers page displaying A S P and A S P NET selected under Verbosity levels.

  9. 如果在步骤 8 中选择了“ASPNET”或“WWW 服务器”跟踪提供程序，请在“选择跟踪提供程序”页的“区域”下选择提供程序要跟踪的一个或多个功能区域。

  10. 单击“完成”。

配置

特性

属性 说明
statusCodes 可选的字符串属性。

指定要跟踪的状态代码。 可以在此列表中输入多个状态代码，使用逗号分隔每个代码。 还可以使用子状态代码（如“404.2、500”）或一系列子状态代码（如“400-599”）来优化状态代码。 如果未指定子状态代码，则会跟踪给定状态代码的所有子状态代码。 状态代码必须为 100 到 999，子状态代码必须为 1 到 999。
timeTaken 可选的 timeSpan 属性。

指定请求在标记为失败并跟踪之前，可以花费的最大处理时间。

默认值为 00:00:00。
traceAllAfterTimeout 可选的布尔属性。

true 如果 IIS 在达到超时时应继续跟踪整个请求，否则，false 如果 IIS 应在发生超时时截断跟踪。

默认值为 false。
verbosity 可选的枚举属性。

指定保存到跟踪日志的最小信息量和信息类型。 如果详细程度设置为“错误”，则当收到第一个详细程度为“错误”或“CriticalError”的跟踪事件时，将创建失败请求跟踪日志文件。

详细程度属性可为以下值之一。

默认值为 Ignore。
值 说明
Ignore 不提供有关请求活动的信息。

数值为 0。
CriticalError 提供有关可能导致进程退出或即将导致进程退出的操作的信息。

数值为 1。
Error 提供有关遇到错误后无法继续处理请求的组件的信息。 这些错误通常表明服务器端存在问题。

数值为 2。
Warning 提供有关遇到错误后仍可继续处理请求的组件的信息。

数值为 3。

子元素

无。

配置示例

以下配置示例展示了如何在 ApplicationHost.config 文件中的服务器级别配置跟踪。 它为所有 .aspx 文件设置跟踪，使用 <traceAreas> 元素设置“ASPNET”提供程序，并针包括“基础结构”、“模块”、“页面”和“AppServices”在内的所有 ASP.NET 区域进行跟踪。 此示例还使用“详细程度”属性将返回到跟踪文件的信息量设置为“警告”。 最后，该示例使用 <failureDefinitions> 元素仅跟踪生成 HTTP 404 状态代码的请求。

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

代码示例

以下示例为所有 *.aspx 页面请求的 ASP.NET 内容 HTTP 500 错误启用详细失败请求跟踪。

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()