Configuring Trace Source Categories

Trace source categories associate log entries with their target listener(s). You can configure the following two category types:

• Categories that specify the logging categories you want to use. When you create a log entry, you can assign it to one or more categories. Each category can filter the log entry based on its severity (such as Critical, Error, Warning, or Information), and route it to one or more trace listeners (logging targets).
• Special Categories that automatically receive all log entries, unprocessed log entries, or log entries where an error occurred during logging. Each of these special categories can filter the log entry based on its severity (such as Critical, Error, Warning, or Information), and route it to one or more trace listeners (logging targets).

Configuring Trace Source Categories

The next procedure describes how to assign log entries to categories by using the configuration tool.

To configure Categories

1. Add a category by clicking the plus sign icon in the Categories pane and clicking Add Category. A new category is added to the configuration with its properties displayed. If a category's properties are not visible, click the expander arrow for the category you want to configure.
2. (Optional) In the properties pane, edit the name of the category.
3. Click the Minimum Severity property and select the severity level of the events that will be assigned to this category. For information about the source level values, see the tables that follow this procedure.
4. Click the Auto Flush property and select True if you want the listener to flush its data to the target after each new entry is written to this source. Select False if you want to flush the entries in your code only when required.
5. To add a logging target listener, click the Listeners property's plus icon and select a listener from the drop-down list.
6. To remove a listener from the list, click the cross icon. You can also make a new selection from the drop-down list for an existing listener to change the contents of the list.
7. Repeat the procedure for each category you require.

Configuring Trace Sources Special Category

The next procedure describes how to configure the special categories. The Logging Errors & Warnings special category receives log entries for errors and warnings that occur during the logging process. The Unprocessed Category special category receives all log entries that are not processed by a source category (such as entries that specify a category that is not configured). The All Events special category receives all log entries.

To configure Special Categories

1. In the Special Categories section, click the special source category you want to configure.
2. (Optional) In the properties pane, type the name of the category.
3. (Optional) Set the Minimum Severity property. For information about the SourceLevels property values, see tables that follow this procedure.
4. Click the Auto Flush property and select True if you want the listener to flush its data to the target after each new entry is written to this source. Select False if you want to flush the entries in your code only when required.
5. To add a logging target listener, click the Listeners property's plus icon and select a listener from the drop-down list.
6. To remove a listener from the list, click the delete(x) icon. You can also make a new selection from the drop-down list for an existing listener to change the contents of the list.
7. Repeat the procedure for each special category source you wish to configure.

Note

If an error occurs when the block writes to a special trace source, there is no error reported and the original log message is discarded.

Source Category Properties

The following table lists the Category Source properties.

Property	Description
Name	The name of the category. The default is Category Source.
Minimum Severity	Possible values are ActivityTracing, All, Critical, Error, Information, Off, Verbose, and Warning. The default is All. See the following table for more information. Represented by the filter element in an XML file. See SourceLevels.
Auto Flush	Specifies whether the listener will flush its data to the target after every new entry is written to this source. The default value is True. When set to False, code can flush the entries when required. Note that it is your responsibility to ensure that all entries are flushed to the target, especially if an exception or failure occurs in the application. Otherwise, you will lose any cached logging information not yet written to the target.
Listeners	The name of the trace listeners that receive log entries and write them to the appropriate destinations.

Severity (SourceLevels) Values

The following table lists the possible values for the severity property of a category or a trace listener.

Value	Description
ActivityTracing	Allows the Stop, Start, Suspend, Transfer, and Resume events through.
All	Allows all events through.
Critical	Allows only Critical events through. A critical event is a fatal error or application crash.
Error	Allows Critical and Error events through. An Error event is a recoverable error.
Information	Allows Critical, Error, Warning, and Information events through. An information event is an informational message.
Off	Does not allow any events through.
Verbose	Allows Critical, Error, Warning, Information, and Verbose events through. A Verbose event is a debugging trace.
Warning	Allows Critical, Error, and Warning events through. A Warning event can indicate both critical and non-critical issues.