Log Entry Processing and Configuration

To understand how you configure and use the Logging Application Block, you must be familiar with the way that the application block processes log entries. The topic Design of the Logging Application Block explains the design of the application block and shows how the individual classes within it relate to each other. However, Figures 1 and 2 will help you to understand how the configuration of the block specifies the way that it processes log entries. Figure 1 shows the configuration of the Logging Application Block after adding objects to several of the configuration sections.

Figure 1
The Logging Application Block section in the configuration tools

Figure 2 shows a schematic of the process that the Logging Application Block carries out and the objects that you can configure for each stage of the process. The main stages correspond to the sections in the configuration shown in Figure 1.

Figure 2
Processing of log entries in the Logging Application Block

The Logging Process Sequence

Your application submits information that the application block should log either by using the Logger class to automatically create a log entry or by directly creating an instance of the LogEntry class and populating it with the information to log. The log entry can define a set of categories that map to the categories defined in the configuration. This mapping controls the processes that the block applies to the log entry (the filters and sources that it uses).

The log writer passes the log entry through the log filters that you define in the configuration. These filters can block the log entry based on its priority, category name, or when logging is not enabled.

If the log filters do not block the log entry, the log writer retrieves the appropriate trace sources. The trace sources you can use consist of a set of category sources that you create and configure, and three special sources that you can use to ensure the application block will record all log entries (for example, if there is an error within the logging system or if the log entry does not match any configured category).

You can configure one or more trace listeners for each of the trace sources. In other words, you can configure a specific set of trace listeners for each category that the message might contain, and for each of the three special sources that might handle the message. The log writer will pass the log entry to the matching trace listeners you specify.

The trace listener then uses a log formatter to transform the information in the log entry into an appropriate format, such as formatted text or binary, and writes the result to the output specific to the type of trace listener. Depending on the trace listener type, the output can go to a file, a database, WMI, Message Queuing (also known as MSMQ), or as an e-mail message.

An Example of Logging Configuration

The following steps illustrate the general process for configuring the Logging Application Block. It assumes you want to use two categories named "Dev" and "Operations."

1. Add the trace listeners you want to use to output the logging information to the TraceListeners section of the configuration and set their properties.
2. Add the formatters you want the trace listeners to use to format the output to the Formatters section of the configuration and set their properties.
3. Set the Formatter property of each trace listener in the TraceListeners section of the configuration to specify the appropriate formatter.
4. Add the categories you want to use to the Category Sources section of the configuration. You can specify the logging level, such as Critical, Error, Warning, or All, in the settings for each category.
5. Add a reference to each of the trace listeners you want to use to output the logging information to each of the categories you created in the Category Sources section of the configuration. Each entry here is a reference to one of the trace listeners you previously configured in the Trace Listeners section. You can add more than one trace listener reference to each CategorySource you create. For example, you could specify the following:
   • A log entry containing the category name "Dev" will go to a Formatted Event Log Trace Listener (so that it appears in Windows Event Log)
   • A log entry containing the category name "Operations" will go to an Email Trace Listener and to an XML Trace Listener.
6. Add a reference to each of the trace listeners you want to use to output the logging information to the appropriate subsections of the Special Sources section of the configuration. For example, you may want to do the following:
   • Send the log entry to an Email Trace Listener when an error occurs within the logging system by adding a reference to this trace listener to the Logging Errors & Warnings section.
   • Send the log entry to a Formatted Event Log Trace Listener when the log entry does not match any configured category by adding a reference to this trace listener to the Unprocessed Category section.
   • Send all log entries, irrespective of category or content, to a Flat File Trace Listener by adding a reference to this trace listener to the All Events section.
7. Finally, add any global log filters you want to use to the Filters section of the configuration and set the appropriate properties. For example, you could use a category filter to block all logging operations except those that specify one of the two categories named "Dev" and "Operations."

For specific details of how to configure each section of the Logging Application Block configuration, see Entering Configuration Information.