Setting Metabase Properties for Custom Logging Modules

  • Article

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:

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.