Campos personalizados em um arquivo de log para um site <customFields>
Visão geral
O elemento <customFields> do elemento <logFile> especifica as configurações de uma coleção de campos personalizados em um log W3C.
Os IIS 8.5 permitem que você registre campos personalizados além do conjunto de logs padrão. Esses campos personalizados podem incluir dados de cabeçalhos de solicitação, cabeçalhos de resposta ou variáveis de servidor. Para registrar esses campos em log, você pode simplesmente definir propriedades de configuração em vez de criar um módulo de registro em log personalizado. Esse recurso só está disponível no nível do site. O formato do arquivo de log deve ser W3C para adicionar campos personalizados.
Quando um campo personalizado tiver sido adicionado ao conjunto padrão, "_x" será acrescentado ao nome do arquivo para mostrar que o arquivo de log contém um campo personalizado. A quantidade total de dados adicionados em campos personalizados não pode exceder 65.536 bytes. Os IIS truncarão os dados se os dados em log personalizados excederem esse valor. A quantidade máxima de dados que podem ser adicionados a um arquivo de log em qualquer campo personalizado é especificada pelo atributo maxCustomFieldLength.
Para configurar um campo personalizado, especifique o nome do campo, o nome de origem e o tipo de origem. Você pode colocar informações personalizadas em uma variável de servidor e registrar a variável de servidor em log. Depois de selecionar o tipo de origem, você pode selecionar um nome de origem existente ou inserir um novo.
Os campos personalizados permitem coletar dados úteis sobre o processo e agregá-los aos logs dos IIS. Em um sistema que contém um balanceador de carga, você pode ver o endereço IP do balanceador de carga no log, mas pode registrar o cabeçalho X-Forwarded-For em um campo personalizado, para que você possa identificar o solicitante original. Você pode registrar o tempo de atividade do processo para ver quantas vezes ele foi reiniciado durante o dia. Se a memória começar a ser usada excessivamente, você poderá determinar em que momento começou a consumir memória, qual página foi solicitada e qual era a ID do cliente (o que seria especialmente útil se estivessem fazendo algo mal-intencionado).
Compatibilidade
| Versão | Observações |
|---|---|
| IIS 10.0 | O elemento <customFields> não foi modificado no IIS 10.0. |
| IIS 8.5 | O elemento <customFields> foi introduzido no IIS 8.5. |
| IIS 8.0 | N/D |
| IIS 7.5 | N/D |
| IIS 7.0 | N/D |
| IIS 6,0 | N/D |
Instalação
O elemento <customFields> está incluído na instalação padrão do IIS 8.5 e versões posteriores.
Instruções
Como adicionar campos personalizados
Abra o Gerenciador dos Serviços de Informações da Internet (IIS):
Se você estiver usando o Windows Server 2012 R2:
- Na barra de tarefas, clique em Gerenciador do Servidor, em Ferramentas e em Gerenciador dos Serviços de Informações da Internet (IIS).
Se você estiver usando o Windows 8.1:
- Mantenha pressionada a tecla Windows, pressione a letra X e clique em Painel de Controle.
- Clique em Ferramentas Administrativas e clique duas vezes em Gerenciador dos Serviços de Informações da Internet (IIS).
No painel Conexões, expanda o servidor, expanda Sites e, em seguida, selecione um site.
Clique duas vezes em Registrar em Log.
Na página inicial Registrar em Log, para Formatar, selecione W3C.
Clique em Selecionar Campos.
Na caixa de diálogo Campos de Registro em Log do W3C, selecione Adicionar Campo.
Na caixa de diálogo Adicionar Campo Personalizado, insira um nome em Nome do Campo e selecione um dos seguintes para o Tipo de Origem: Cabeçalho de Solicitação, Cabeçalho de Resposta ou Variável do Servidor.
Em Origem, selecione uma origem na lista ou insira o nome de uma origem personalizada.
Clique em OK e clique em OK novamente.
No painel Ação, clique em Aplicar.
Como configurar o comprimento máximo do campo personalizado
Abra o Gerenciador dos Serviços de Informações da Internet (IIS):
Se você estiver usando o Windows Server 2012 R2:
- Na barra de tarefas, clique em Gerenciador do Servidor, em Ferramentas e em Gerenciador dos Serviços de Informações da Internet (IIS).
Se você estiver usando o Windows 8.1:
- Mantenha pressionada a tecla Windows, pressione a letra X e clique em Painel de Controle.
- Clique em Ferramentas Administrativas e clique duas vezes em Gerenciador dos Serviços de Informações da Internet (IIS).
No painel Conexões, selecione o servidor e, na área Gerenciamento, clique duas vezes no Editor de Configuração.
No Editor de Configuração, para a seção, selecione system.applicationHost e selecione sites.
Clique em (Coleção) e, em seguida, nas reticências.
Selecione o site, expanda logFile, depois expanda customFields e clique em maxCustomFieldLength.
Para maxCustomFieldLength, insira a quantidade máxima de dados que podem ser adicionados a um arquivo de log em qualquer campo personalizado, em bytes.
Feche o Editor de Coleção e, no painel Ação, clique em Aplicar.
Configuração
O elemento <customFields> é configurado no nível do site.
Atributos
| Atributo | Descrição |
|---|---|
maxCustomFieldLength |
Atributo uint opcional. A quantidade máxima de dados, em bytes, que podem ser adicionados a um arquivo de log em qualquer campo personalizado. O intervalo é de 2 a 65.536. O valor padrão é 4096. |
Elementos filho
| Elemento | Descrição |
|---|---|
add |
Elemento opcional. Especifica as configurações de um campo personalizado adicionado a um log W3C. |
Exemplo de configuração
O exemplo de configuração a seguir usa o elemento customFields e seu elemento filho add para especificar as configurações de campo personalizado de log para logs o site padrão.
<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>
Exemplo de código
Os exemplos a seguir configuram campos personalizados para um log W3C para um site.
AppCmd.exe
appcmd.exe set config -section:system.applicationHost/sites /+"[name='ContosoSite'].logFile.customFields.[logFieldName='ContosoField',sourceName='ContosoSource',sourceType='ServerVariable']" /commit:apphost
Observação
Defina o parâmetro commit para apphost quando usar AppCmd.exe para definir essas configurações. Isso confirma as definições de configuração para a seção de local apropriado no arquivo 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'}