แก้ไข

แชร์ผ่าน

Adding Custom Fields to a Log File for a Site <add>

  • บทความ

Overview

The <add> element under the <customField> element controls the configuration settings for a custom field for a W3C log for a site.

IIS 8.5 enables you to log custom fields in addition to the standard logged set. These custom fields can include data from request headers, response headers, or server variables. To log these fields, you can simply set configuration properties rather than creating a custom logging module. This feature is available only at the site level. The log file format must be W3C to add custom fields.

When a custom field has been added to the standard set, "_x" will be appended to the file name to show that the log file contains a custom field. The total amount of data added in custom fields cannot exceed 65,536 bytes. IIS will truncate the data if the custom logged data exceeds that amount. The maximum amount of data that can be added to a log file in any one custom field is specified by the maxCustomFieldLength attribute.

To configure a custom field, specify the field name, the source name, and the source type. You can put custom information into a server variable, and log the server variable. Once you have selected the source type, you can either select an existing source name or enter a new source name.

Custom fields enable you to collect useful data about the process and aggregate it to the IIS logs. In a system containing a load balancer, you might see the load balancer's IP address in the log, but you could log the X-Forwarded-For header in a custom field, so you can know the original requester. You could log process uptime to see how many times the process restarted during the day. If memory starts being used excessively, you can determine at which time it started to consume memory, which page was requested, and what was the ID of the client (which would be especially useful if they were doing something malicious).

Compatibility

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

Setup

The <add> element is included in the default installation of IIS 8.5 and later.

How To

How to add custom fields

  1. Open Internet Information Services (IIS) Manager:

    • If you are using Windows Server 2012 R2:

      • On the taskbar, click Server Manager, click Tools, and then click Internet Information Services (IIS) Manager.

    • If you are using Windows 8.1:

      • Hold down the Windows key, press the letter X, and then click Control Panel.
      • Click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.

  2. In the Connections pane, expand the server, expand Sites, and then select a site.

  3. Double-click Logging.

  4. In the Logging home page, for Format, select W3C.

  5. Click Select Fields.

  6. In the W3C Logging Fields dialog box, click Add Field.

  7. In the Add Custom Field dialog box, enter a name in Field name, and select one of the following for the Source Type: Request Header, Response Header, or Server Variable.

  8. In Source, select a source from the list, or enter the name of a custom source.

  9. Click OK, then click OK again.

  10. In the Action pane, click Apply.

    Screenshot of Add Custom Field dialog box with Request Header selected in the Source field.

How to configure the maximum custom field length

  1. Open Internet Information Services (IIS) Manager:

    • If you are using Windows Server 2012 R2:

      • On the taskbar, click Server Manager, click Tools, and then click Internet Information Services (IIS) Manager.

    • If you are using Windows 8.1:

      • Hold down the Windows key, press the letter X, and then click Control Panel.
      • Click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.

  2. In the Connections pane, select the server, and then in the Management area, double-click Configuration Editor.

  3. In the Configuration Editor, for the section, select system.applicationHost, and then select sites.

  4. Click (Collection), and then click the ellipsis.

  5. Select the site, expand logFile, expand customFields, and then click maxCustomFieldLength.

  6. For maxCustomFieldLength, enter the maximum amount of data that can be added to a log file in any one custom field, in bytes.

  7. Close the Collection Editor, and then in the Action pane, click Apply.

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

Configuration

The <add> element is configured at the site level.

Attributes

Attribute Description
logFieldName Required string attribute.

Specifies the custom field to be added to the log file. The field name cannot contain spaces.
sourceName Required string attribute.

Specifies the name of the HTTP header or server variable that contains values to be added to a custom field of the log. The name can be a custom source string.
sourceType Required enum attribute.

The type of source for the data to be added to a custom field in the log. Can be RequestHeader (value = 0), ResponseHeader (value = 1), or ServerVariable (value = 2).

Child Elements

None.

Configuration Sample

The following configuration example uses the customFields element and its add child element to specify the log custom field settings for the Default Web Site.

<sites>
    <site name="Default Web Site" id="1">
        <logFile logFormat="W3C" logTargetW3C="File, ETW">
            <customFields maxCustomFieldLength="4095">
                <clear />
                <add logFieldName="X-Forwarded-For" sourceName="X_FORWARDED_FOR" 
                    sourceType="RequestHeader" />
            </customFields>
        </logFile>
    </site>   
</sites>

Sample Code

The following examples configure custom fields for a W3C log for a site.

AppCmd.exe

appcmd.exe set config  -section:system.applicationHost/sites /+"[name='ContosoSite'].logFile.customFields.[logFieldName='ContosoField',sourceName='ContosoSource',sourceType='ServerVariable']" /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 sitesSection = config.GetSection("system.applicationHost/sites");
            ConfigurationElementCollection sitesCollection = sitesSection.GetCollection();
            
            ConfigurationElement siteElement = FindElement(sitesCollection, "site", "name", @"ContosoSite");

            if (siteElement == null) throw new InvalidOperationException("Element not found!");
            
            
            ConfigurationElement logFileElement = siteElement.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();
        }
    }

   private static ConfigurationElement FindElement(ConfigurationElementCollection collection, string elementTagName, params string[] keyValues)
   {
      foreach (ConfigurationElement element in collection)
      {
         if (String.Equals(element.ElementTagName, elementTagName, StringComparison.OrdinalIgnoreCase))
         {
            bool matches = true;
            for (int i = 0; i < keyValues.Length; i += 2)
            {
               object o = element.GetAttributeValue(keyValues[i]);
               string value = null;
               if (o != null)
               {
                  value = o.ToString();
               }
               if (!String.Equals(value, keyValues[i + 1], StringComparison.OrdinalIgnoreCase))
               {
                  matches = false;
                  break;
               }
            }
            if (matches)
            {
               return element;
            }
         }
      }
      return null;
   }
}

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 sitesCollection As ConfigurationElementCollection = sitesSection.GetCollection
         Dim siteElement As ConfigurationElement = FindElement(sitesCollection, "site", "name", "ContosoSite")
         If (siteElement Is Nothing) Then
             Throw New InvalidOperationException("Element not found!")
         End If
         Dim logFileElement As ConfigurationElement = siteElement.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

   Private Function FindElement(ByVal collection As ConfigurationElementCollection, ByVal elementTagName As String, ByVal ParamArray keyValues() As String) As ConfigurationElement
      For Each element As ConfigurationElement In collection
         If String.Equals(element.ElementTagName, elementTagName, StringComparison.OrdinalIgnoreCase) Then
            Dim matches As Boolean = True
            Dim i As Integer
            For i = 0 To keyValues.Length - 1 Step 2
               Dim o As Object = element.GetAttributeValue(keyValues(i))
               Dim value As String = Nothing
               If (Not (o) Is Nothing) Then
                  value = o.ToString
               End If
               If Not String.Equals(value, keyValues((i + 1)), StringComparison.OrdinalIgnoreCase) Then
                  matches = False
                  Exit For
               End If
            Next
            If matches Then
               Return element
            End If
         End If
      Next
      Return Nothing
   End Function


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 sitesCollection = sitesSection.Collection;

var siteElementPos = FindElement(sitesCollection, "site", ["name", "ContosoSite"]);
if (siteElementPos == -1) throw "Element not found!";
var siteElement = sitesCollection.Item(siteElementPos);

var logFileElement = siteElement.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();


function FindElement(collection, elementTagName, valuesToMatch) {
   for (var i = 0; i < collection.Count; i++) {
      var element = collection.Item(i);
      if (element.Name == elementTagName) {
         var matches = true;
         for (var iVal = 0; iVal < valuesToMatch.length; iVal += 2) {
            var property = element.GetPropertyByName(valuesToMatch[iVal]);
            var value = property.Value;
            if (value != null) {
               value = value.toString();
            }
            if (value != valuesToMatch[iVal + 1]) {
               matches = false;
               break;
            }
         }
         if (matches) {
            return i;
         }
      }
   }
   return -1;
}

VBScript

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

Set sitesSection = adminManager.GetAdminSection("system.applicationHost/sites", "MACHINE/WEBROOT/APPHOST")

Set sitesCollection = sitesSection.Collection

siteElementPos = FindElement(sitesCollection, "site", array ("name", "ContosoSite"))
if (siteElementPos = -1) THEN throw "Element not found!"
Set siteElement = sitesCollection.Item(siteElementPos)

Set logFileElement = siteElement.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()

Function FindElement(collection, elementTagName, valuesToMatch)
   For i = 0 To CInt(collection.Count) - 1
      Set element = collection.Item(i)
      If element.Name = elementTagName Then
         matches = True
         For iVal = 0 To UBound(valuesToMatch) Step 2
            Set property = element.GetPropertyByName(valuesToMatch(iVal))
            value = property.Value
            If Not IsNull(value) Then
               value = CStr(value)
            End If
            If Not value = CStr(valuesToMatch(iVal + 1)) Then
               matches = False
               Exit For
            End If
         Next
         If matches Then
            Exit For
         End If
      End If
   Next
   If matches Then
      FindElement = i
   Else
      FindElement = -1
   End If
End Function

PowerShell

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