通过

向日志文件添加默认自定义字段 <add>

  • 项目

概述

<customFields> 元素下的 <add> 元素指定在 W3C 日志中添加默认自定义字段的配置设置。

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

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

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

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

兼容性

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

安装

<add> 元素包含在 IIS 8.5 的默认安装中。

操作方式

如何添加默认自定义字段

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

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

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

    • 如果使用的是 Windows 8.1：

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

  2. 在“连接”窗格中，选择服务器。

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

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

  5. 单击“选择字段”。

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

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

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

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

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

    Screenshot of the Add Custom Field dialog with the default options.

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

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

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

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

    • 如果使用的是 Windows 8.1：

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

  2. 在“连接”窗格中，选择服务器，然后在“管理”区域中，双击“配置编辑器”。

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

  4. 单击 siteDefaults。

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

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

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

    Screenshot of the custom Fields section of the log File Properties. Max Custom Field Length is set to 4095.

配置

<add> 元素在服务器级别配置。

特性

属性 说明
logFieldName 必需的字符串属性。

指定要添加到日志文件的默认自定义字段。 字段名称不能包含空格。
sourceName 必需的字符串属性。

指定包含要添加到日志默认自定义字段的值的 HTTP 头或服务器变量的名称。 名称可以是自定义源字符串。
sourceType 必需枚举属性。

要添加到日志默认自定义字段的数据的源类型。 可以是 RequestHeader（值 = 0）、ResponseHeader（值 = 1）或 ServerVariable（值 = 2）。

子元素

无。

配置示例

以下配置示例使用 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'}