日志文件中的默认自定义字段 <customFields>

概述

<logFile> 元素的 <customFields> 元素指定 W3C 日志中默认自定义字段集合的配置设置。

除了标准记录集之外,IIS 8.5 还支持记录自定义字段。 这些自定义字段可包括来自请求头、响应头或服务器变量的数据。 若要记录这些字段,只需设置配置属性,而无需创建自定义记录模块。 此功能只能在站点级别使用。 日志文件格式必须是 W3C 才能添加自定义字段。

将自定义字段添加到标准集后,文件名后将附加“_x”,以显示日志文件包含自定义字段。 自定义字段中添加的数据总量不能超过 65,536 字节。 如果自定义记录的数据超过该数量,IIS 将截断数据。 任何一个自定义字段中可添加到日志文件的最大数据量由 maxCustomFieldLength 属性指定。

若要配置自定义字段,请指定字段名称、源名称和源类型。 可以将自定义信息放入服务器变量中,并记录服务器变量。 选择源类型后,可以选择现有源名称或输入新的源名称。

使用自定义字段可以收集有关进程的有用数据并将其聚合到 IIS 日志中。 在包含负载均衡器的系统中,可能会在日志中看到负载均衡器的 IP 地址,但可以在自定义字段中记录 X-Forwarded-For 头,以便了解原始请求者。 可以记录进程运行时间,查看进程在一天内重启了多少次。 如果内存开始过度使用,就可以确定内存是何时开始消耗的、请求的是哪个页面,以及客户端的 ID 是什么(如果他们在恶意操作,这一点将特别有用)。

兼容性

版本 说明
IIS 10.0 <customFields> 元素在 IIS 10.0 中未进行修改。
IIS 8.5 <customFields> 元素是在 IIS 8.5 中引入的。
IIS 8.0 空值
IIS 7.5 空值
IIS 7.0 空值
IIS 6.0 空值

安装

<customFields> 元素包含在 IIS 8.5 及更高版本的默认安装中。

操作方式

如何添加默认自定义字段

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

    • 如果使用的是 Windows Server 2012 R2:

      • 在任务栏上,单击“服务器管理器”,单击“工具”,然后单击“Internet Information Services (IIS)管理器”
    • 如果使用的是 Windows 8.1:

      • 按住 Windows 键,按字母 X,然后单击“控制面板”。
      • 单击“管理工具”,然后双击“Internet 信息服务(IIS)管理器”。
  2. 在“连接”窗格中,选择服务器

  3. 在 IIS 部分中双击“日志记录”。

  4. 在“日志记录”主页中,对于“格式”,选择“W3C”

  5. 单击“选择字段”

  6. 在“W3C 日志记录字段”对话框中,单击“添加字段”

  7. 在“添加自定义字段”对话框中,在“字段名”中输入名称(不带空格),并为“源类型”选择下列名称之一:“请求头”、“响应头”或“服务器变量”

  8. 在“源”中,从列表中选择源,或输入自定义源的名称

  9. 单击“确定”,然后再次单击“确定”

  10. 在“操作”窗格中,单击“应用”

    Screenshot shows Add Custom Field dialog box with Field Name box. Request Header selected in the Source Type box.

如何配置默认的最大自定义字段长度

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

    • 如果使用的是 Windows Server 2012 R2:

      • 在任务栏上,单击“服务器管理器”,单击“工具”,然后单击“Internet Information Services (IIS)管理器”
    • 如果使用的是 Windows 8.1:

      • 按住 Windows 键,按字母 X,然后单击“控制面板”。
      • 单击“管理工具”,然后双击“Internet 信息服务(IIS)管理器”。
  2. 在“连接”窗格中,选择服务器,然后在“管理”区域中,双击“配置编辑器”

  3. 在“配置编辑器”中,对于“部分”,选择“system.applicationHost”,然后选择“站点”

  4. 单击 siteDefaults

  5. 选择站点,展开“logFile”,展开“customFields”,然后单击“maxCustomFieldLength”

  6. 对于 maxCustomFieldLength,输入任何一个自定义字段中可添加到日志文件的最大数据量(以字节为单位)

  7. 关闭“集合编辑器”,然后在“操作”窗格中,单击“应用”

    Screenshot of log File pane with Custom Fields node expanded and max Custom Field Length selected.

配置

默认设置的 <customFields> 元素是在服务器级别配置的。

特性

属性 说明
maxCustomFieldLength 可选 uint 属性。

任何一个自定义字段中可添加到日志文件的最大数据量(以字节为单位)。

范围从 2 到 65,536。 默认值为 4096

子元素

元素 说明
add 可选元素。

指定 W3C 日志中默认自定义字段的配置设置。

配置示例

以下配置示例使用 customFields 元素及其 add 子元素来指定 W3C 的默认自定义字段设置。

<siteDefaults>
    <logFile logFormat="W3C" directory="%SystemDrive%\inetpub\logs\LogFiles" flushByEntryCountW3CLog="0">
        <customFields>
            <clear />
            <add logFieldName="ContosoField" sourceName="ContosoSource" sourceType="ServerVariable" />
        </customFields>
    </logFile>
</siteDefaults>

代码示例

以下示例为 W3C 日志配置默认自定义字段。

AppCmd.exe

appcmd.exe set config  -section:system.applicationHost/sites /+"siteDefaults.logFile.customFields.[logFieldName='ContosoField',sourceName='ContosoSource',sourceType='ServerVariable']" /commit:apphost

注意

使用 AppCmd.exe 配置这些设置时,必须确保将 commit 参数设置为 apphost。 这会将配置设置提交到 ApplicationHost.config 文件中的相应位置部分。

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 sitesSection = config.GetSection("system.applicationHost/sites");
            ConfigurationElement siteDefaultsElement = sitesSection.GetChildElement("siteDefaults");
            ConfigurationElement logFileElement = siteDefaultsElement.GetChildElement("logFile");
            ConfigurationElement customFieldsElement = logFileElement.GetChildElement("customFields");
            ConfigurationElementCollection customFieldsCollection = customFieldsElement.GetCollection();
            
            ConfigurationElement addElement = customFieldsCollection.CreateElement("add");
            addElement["logFieldName"] = @"ContosoField";
            addElement["sourceName"] = @"ContosoSource";
            addElement["sourceType"] = @"ServerVariable";
            customFieldsCollection.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 sitesSection As ConfigurationSection =  config.GetSection("system.applicationHost/sites")
        Dim siteDefaultsElement As ConfigurationElement =  sitesSection.GetChildElement("siteDefaults")
        Dim logFileElement As ConfigurationElement =  siteDefaultsElement.GetChildElement("logFile")
        Dim customFieldsElement As ConfigurationElement =  logFileElement.GetChildElement("customFields")
        Dim customFieldsCollection As ConfigurationElementCollection =  customFieldsElement.GetCollection
        Dim addElement As ConfigurationElement =  customFieldsCollection.CreateElement("add")
        addElement("logFieldName") = "ContosoField"
        addElement("sourceName") = "ContosoSource"
        addElement("sourceType") = "ServerVariable"
        customFieldsCollection.Add(addElement)
        serverManager.CommitChanges
    End Sub
End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";

var sitesSection = adminManager.GetAdminSection("system.applicationHost/sites", "MACHINE/WEBROOT/APPHOST");
var siteDefaultsElement = sitesSection.ChildElements.Item("siteDefaults");
var logFileElement = siteDefaultsElement.ChildElements.Item("logFile");
var customFieldsElement = logFileElement.ChildElements.Item("customFields");

var customFieldsCollection = customFieldsElement.Collection;

var addElement = customFieldsCollection.CreateNewElement("add");
addElement.Properties.Item("logFieldName").Value = "ContosoField";
addElement.Properties.Item("sourceName").Value = "ContosoSource";
addElement.Properties.Item("sourceType").Value = "ServerVariable";
customFieldsCollection.AddElement(addElement);

adminManager.CommitChanges();

VBScript

Set adminManager = CreateObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"

Set sitesSection = adminManager.GetAdminSection("system.applicationHost/sites", "MACHINE/WEBROOT/APPHOST")
Set siteDefaultsElement = sitesSection.ChildElements.Item("siteDefaults")
Set logFileElement = siteDefaultsElement.ChildElements.Item("logFile")
Set customFieldsElement = logFileElement.ChildElements.Item("customFields")

Set customFieldsCollection = customFieldsElement.Collection

Set addElement = customFieldsCollection.CreateNewElement("add")
addElement.Properties.Item("logFieldName").Value = "ContosoField"
addElement.Properties.Item("sourceName").Value = "ContosoSource"
addElement.Properties.Item("sourceType").Value = "ServerVariable"
customFieldsCollection.AddElement(addElement)

adminManager.CommitChanges()

PowerShell

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST'  -filter "system.applicationHost/sites/siteDefaults/logFile/customFields" -name "." -value @{logFieldName='ContosoField';sourceName='ContosoSource';sourceType='ServerVariable'}