日志文件中的默认自定义字段 <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 及更高版本的默认安装中。
操作方式
如何添加默认自定义字段
打开 Internet Information Services (IIS) 管理器:
如果使用的是 Windows Server 2012 R2:
- 在任务栏上,单击“服务器管理器”,单击“工具”,然后单击“Internet Information Services (IIS)管理器”。
如果使用的是 Windows 8.1:
- 按住 Windows 键,按字母 X,然后单击“控制面板”。
- 单击“管理工具”,然后双击“Internet 信息服务(IIS)管理器”。
在“连接”窗格中,选择服务器。
在 IIS 部分中双击“日志记录”。
在“日志记录”主页中,对于“格式”,选择“W3C”。
单击“选择字段”。
在“W3C 日志记录字段”对话框中,单击“添加字段”。
在“添加自定义字段”对话框中,在“字段名”中输入名称(不带空格),并为“源类型”选择下列名称之一:“请求头”、“响应头”或“服务器变量”。
在“源”中,从列表中选择源,或输入自定义源的名称。
单击“确定”,然后再次单击“确定”。
在“操作”窗格中,单击“应用”。
如何配置默认的最大自定义字段长度
打开 Internet Information Services (IIS) 管理器:
如果使用的是 Windows Server 2012 R2:
- 在任务栏上,单击“服务器管理器”,单击“工具”,然后单击“Internet Information Services (IIS)管理器”。
如果使用的是 Windows 8.1:
- 按住 Windows 键,按字母 X,然后单击“控制面板”。
- 单击“管理工具”,然后双击“Internet 信息服务(IIS)管理器”。
在“连接”窗格中,选择服务器,然后在“管理”区域中,双击“配置编辑器”。
在“配置编辑器”中,对于“部分”,选择“system.applicationHost”,然后选择“站点”。
单击 siteDefaults。
选择站点,展开“logFile”,展开“customFields”,然后单击“maxCustomFieldLength”。
对于 maxCustomFieldLength,输入任何一个自定义字段中可添加到日志文件的最大数据量(以字节为单位)。
关闭“集合编辑器”,然后在“操作”窗格中,单击“应用”。
配置
默认设置的 <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'}