사이트 <customFields에 대한 로그 파일의 사용자 지정 필드>

아티클
07/19/2023

개요

<customFields> 요소의 <logFile> 요소는 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 이상의 기본 설치에 포함됩니다.

방법

사용자 지정 필드를 추가하는 방법

IIS(인터넷 정보 서비스) 관리자를 엽니다.
- Windows Server 2012 R2를 사용하는 경우:
  - 작업 표시줄에서 서버 관리자 클릭하고 도구를 클릭한 다음 IIS(인터넷 정보 서비스) 관리자를 클릭합니다.
- Windows 8.1 사용하는 경우:
  - Windows 키를 누른 채로 문자 X를 누른 다음 제어판 클릭합니다.
  - 관리 도구를 클릭한 다음 IIS(인터넷 정보 서비스) 관리자를 두 번 클릭합니다.
연결 창에서 서버를 확장하고 사이트를 확장한 다음 사이트를 선택합니다.
로깅을 두 번 클릭합니다.
로깅 홈페이지의 형식에서 W3C를 선택합니다.
필드 선택을 클릭합니다.
W3C 로깅 필드 대화 상자에서 필드 추가를 클릭합니다.
사용자 지정 필드 추가 대화 상자에서 필드 이름에 이름을 입력하고 원본 유형에 대해 요청 헤더, 응답 헤더 또는 서버 변수 중 하나를 선택합니다.
원본에서 목록에서 원본을 선택하거나 사용자 지정 원본의 이름을 입력합니다.
확인을 클릭한 다음 확인을 다시 클릭합니다.
작업 창에서 적용을 클릭합니다.

최대 사용자 지정 필드 길이를 구성하는 방법

IIS(인터넷 정보 서비스) 관리자를 엽니다.
- Windows Server 2012 R2를 사용하는 경우:
  - 작업 표시줄에서 서버 관리자 클릭하고 도구를 클릭한 다음 IIS(인터넷 정보 서비스) 관리자를 클릭합니다.
- Windows 8.1 사용하는 경우:
  - Windows 키를 누른 채로 문자 X를 누른 다음 제어판 클릭합니다.
  - 관리 도구를 클릭한 다음 IIS(인터넷 정보 서비스) 관리자를 두 번 클릭합니다.
연결 창에서 서버를 선택한 다음 관리 영역에서 구성 편집기를 두 번 클릭합니다.
구성 편집기에서 섹션에서system.applicationHost를 선택한 다음 사이트를 선택합니다.
(컬렉션)을 클릭한 다음 줄임표를 클릭합니다.
사이트를 선택하고 logFile을 확장하고 customFields를 확장한 다음 maxCustomFieldLength를 클릭합니다.
maxCustomFieldLength의 경우 하나의 사용자 지정 필드에 로그 파일에 추가할 수 있는 최대 데이터 양을 바이트 단위로 입력합니다.
컬렉션 편집기를 닫은 다음 작업 창에서 적용을 클릭합니다.

구성

<customFields> 요소는 사이트 수준에서 구성됩니다.

특성

attribute	Description
`maxCustomFieldLength`	선택적 uint 특성입니다. 하나의 사용자 지정 필드의 로그 파일에 추가할 수 있는 최대 데이터 양(바이트)입니다. 범위는 2에서 65,536까지입니다. 기본값은 `4096`입니다.

자식 요소

요소	Description
`add`	선택적 요소입니다. W3C 로그에 추가된 사용자 지정 필드의 구성 설정을 지정합니다.

구성 샘플

다음 구성 예제에서는 요소와 해당 add 자식 요소를 사용하여 customFields 기본 웹 사이트에 대한 로그 사용자 지정 필드 설정을 지정합니다.

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

샘플 코드

다음 예제에서는 사이트에 대한 W3C 로그에 대한 사용자 지정 필드를 구성합니다.

AppCmd.exe

appcmd.exe set config  -section:system.applicationHost/sites /+"[name='ContosoSite'].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");
            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'}

다음을 통해 공유