Setting Metabase Properties for Custom Logging Modules
To properly configure a new custom logging module that does not register itself with IIS, or to log custom information to an existing, standard IIS logging module, you must access and modify the administration properties stored in the IIS metabase.
Metabase Properties for Custom Logging Modules
The logging module determines which methods to query for by examining the LogExtFileFlags identifier in the metabase. LogExtFileFlags is a DWORD of flag bits that specify individual methods of the IInetLogInformation interface. For example, the constant LogExtFileBytesSent has been defined as value 0x00001000 for the DWORD. If this constant is specified in the metabase, the logging module queries IInetLogInformation for the GetBytesSent method, which returns the number of bytes sent as a result of the HTTP request.
The flags in the LogExtFileFlags identifier can be set with the Internet Service Manager.
The flags can also be set by a script. The following script sets the LogExtFileBytesSent flag in the metabase to True.
Dim CurrServer
Set CurrServer = GetObject("IIS:/LocalHost/W3svc/1")
CurrServer.LogExtFileBytesSent = True
CurrServer.SetInfo
Metabase Properties for Custom Logging Information
In IIS versions 5.0 and later, there is a special metabase node, under /LM/Logging, called CustomLogging. This node stores metadata, in the form of properties, that describe the various types of information that can be logged by IIS.
When the LogCustomInformation method is called, the custom logging module-provided ILogPluginEx interface, the CustomLogging metabase subtree is used to determine how to record the custom information.
Each logging information field, such as "time," has a corresponding child node off of CustomLogging. For each logging field, the following information is stored in the metabase:
LogCustomPropertyName: Name of field, displayed in the user interface ("time").
LogCustomPropertyHeader: Abbreviated header for field, recorded in the log ("t").
LogCustomPropertyDataType: Data type of field (string).
LogCustomPropertyID: Metabase property ID of the property that stores the logging control flags (LogExtFileFlags).
LogCustomPropertyMask: Field mask, which specifies which bit in the aforementioned control flags controls whether this field is logged or not (0x01).
The implementer of LogCustomInformation (either IIS or your custom logging module) is responsible for checking to see whether logging is enabled or disabled for that particular field, using the last two items in the previous list.
In general, custom logging information fields are clustered in logical groupings and placed in a child subnode to CustomLogging. For instance, IIS creates two subnodes, ProcessAccounting and ExtendedProperties, that contain the individual field nodes for the process accounting and W3C Extended logging module, respectively. Each of these group nodes should specify to what Internet services the logging fields apply, using the LogCustomPropertyServicesString property.
Note
Two logging information fields, time and date, are considered global, and are stored as immediate children of CustomLogging. It is generally not necessary to duplicate these fields in the individual field groups that are children of CustomLogging, unless you desire some special behavior.
Adding a Logging Module
For your logging module to be available through the IIS administrative user interface, you should add it to the /LM/LOGGING path of the metabase. You should give the key the same name as the custom logging module, and it should contain two values: LogModuleId and LogModuleUiId. LogModuleId should contain a string that represents the custom module's GUID, and LogModuleUiId should contain a string that represents the GUID of the custom module's user interface.
If you use a script to add a logging module to the /LM/LOGGING path, you should add the GUID for the log module to the LogModuleList Automation property.
The following script demonstrates how to add a custom logging module:
Dim oWebInfo, oLogging, oNewLogMod
Dim strNewModName, strModId, strModUiId
' sample name and UUIDs (note: UUIDs given here are from ODBC Logging module)
' ****INSERT REAL NAME AND UUIDS HERE***
strNewModName = "My New Logging Module"
strModId = "{FF16065B-DE82-11CF-BC0A-00AA006111E0}"
strModUiId = "{31DCAB86-BB3E-11D0-9299-00C04FB6678B}"
' Create a new logging module node in the master logging tree, with the name specified by strNewModName
Set oLogging = GetObject( "IIS://Localhost/Logging" )
Set oNewLogMod = oLogging.Create( "IIsLogModule", strNewModName )
' Set configuration settings for new module
oNewLogMod.LogModuleId = strModId
oNewLogMod.LogModuleUiId = strModUiId
' Make sure the properties get written back to the object from the ADSI property cache
oNewLogMod.SetInfo
' Finally, add new logging module to the list of available logging modules
Set oWebInfo = GetObject( "IIS://Localhost/W3SVC/Info" )
oWebInfo.LogModuleList = oWebInfo.LogModuleList & "," & strNewModName
' Again, write property back to object from property cache
oWebInfo.SetInfo
Note
The logging module must be resident and registered on the server machine.
Adding a Custom Logging Module to a Service
Each service defined in the metabase includes a LogModuleList key at the /LM/ <Service>/Info node. This key contains a comma-delimited list of logging modules available for that particular service. For your custom logging module to be available to a particular service, its name must be included in this list. You can use a script to add the name to the LogModuleList administration property.