Trace Listener Properties

  • Article

These tables explain the properties for the different trace listeners. There are tables for the following trace listeners:

  • Database Trace Listener. This trace listener writes formatted log entries to a database.
  • E-mail Trace Listener. This trace listener sends log entries as e-mail messages.
  • Event Log Trace Listener. This trace listener formats log entries and writes them to Windows Event Log.
  • Flat File Trace Listener. This trace listener writes log entries to a text file.
  • Message Queuing Trace Listener. This trace listener writes log entries to a message queue.
  • Rolling Flat File Trace Listener. This trace listener creates a new log file depending on the current log file age and/or size.
  • System Diagnostics Trace Listener. This is one of the .NET Framework trace listeners such as the Console Trace Listener.
  • WMI Trace Listener. This trace listener raises a WMI management event for each log entry received.
  • XML Trace Listener. This trace listener is used to output log messages to an XML formatted file.

Database Trace Listener

The following table lists the properties that you can set when you add a Database Trace Listener.

Property

Description

Add Category Procedure

The name of the stored procedure that adds a category. The default is AddCategory. This is required.

Database Instance

The name of the database instance to use as configured in the Data Settings section of the configuration. This is required.

Severity Filter

Applies a filter that selects the level of message that it will detect. The valid values are All (the default), Off, Critical, Error, Warning, Information, Verbose, and ActivityTracing. The setting effectively means "the specified level and everything more important." For example, the Warning setting will detect warnings, errors, and critical events.

Formatter

The formatter to use with this trace listener. Select one from the drop-down list. The default is none. This is optional.

Name

The name of the trace listener. The default is Database Trace Listener. This is required.

Trace Output Options

A property used by trace listeners that do not output to a text formatter to determine which options, or elements, should be included in the trace output. Possible values are CallStack, DateTime, LogicalOperationStack, None, ProcessId, ThreadId, and Timestamp. The default is None. For an explanation of these values, see TraceOutputOptions Values. This is optional.

Write To Log Procedure

The name of the stored procedure that writes the log entries. The default is WriteLog. This is required.

Email Trace Listener

The following table lists the properties that you can set when you add an e-mail trace listener.

Property

Description

Authentication Mode

A value from the EmailAuthenticationMode enumeration that specifies how the listener will authenticate the user. Valid values are None, WindowsCredentials, and UserNameAndPassword.

Severity Filter

Applies a filter that selects the level of message that it will detect. The valid values are All (the default), Off, Critical, Error, Warning, Information, Verbose, and ActivityTracing. The setting effectively means "the specified level and everything more important." For example, the Warning setting will detect warnings, errors, and critical events.

Formatter Name

The formatter to use with this trace listener. Select one from the drop-down list. The default is none. This is optional.

From Address

The address where the log entry originated. The default is from@example.com. This is required.

Name

The name of the trace listener. The default is Email Trace Listener. This is required.

Authentication Password

Password when authenticating with user name and password.

Smtp Port

The SMTP port that receives e-mail messages. The default is 25. This is optional.

Smtp Server

The SMTP server used to send e-mail messages. The default is 127.0.0.1. This is optional.

Subject Line Suffix

The subject line suffix. This is optional.

Subject Line Prefix

The subject line prefix. This is optional.

To Address

The address where the log entry is sent. The default is to@example.com. This is required.

Trace Output Options

Trace listeners that do not output to a text formatter use this property to determine which options, or elements, should be included in the trace output. Possible values are: CallStack, DateTime, LogicalOperationStack, None, ProcessId, ThreadId, and Timestamp. The default is None. For an explanation of these values, see TraceOutputOptions Values. This is optional.

Authentication User Name

User name when authenticating with user name and password.

Use SSL

Specifies if the e-mail trace listener should use SSL when connecting to the mail server. Set to True to use SSL to connect, or False to use an unencrypted connection. The default is False

Note

The configuration files are not encrypted by default. A configuration file may contain sensitive information about connection strings, user IDs, passwords, database servers, and catalogs. You should protect this information against unauthorized read/write operations by using encryption techniques. For information about how to encrypt configuration files, see Encrypting Configuration Data and Configuring Enterprise Library.

In addition to this problem, e-mail messages exchanged with a SMTP server could be intercepted while in transit by a malicious user running a network sniffer or monitoring application. You can mitigate this problem by supporting Transport Layer Security or S/Mime with encryption of the e-mail messages.

Flat File Trace Listener

The following table lists the properties that you can set when you add a flat file trace listener.

Property

Description

File Name

The name of the file where entries are written. The default name is trace.log. This is a required value. It can include environment variables such as %WINDIR%, %TEMP%, and %USERPROFILE%.

Severity Filter

Applies a filter that selects the level of message that it will detect. The valid values are All (the default), Off, Critical, Error, Warning, Information, Verbose, and ActivityTracing. The setting effectively means "the specified level and everything more important." For example, the Warning setting will detect warnings, errors, and critical events.

Message Footer

Additional information contained in the file footer. The default is "----------------------------------------." This is optional.

Formatter Name

The formatter to use with this trace listener. Select one from the drop-down list. The default is none. This is optional.

Message Header

Additional information contained in the file header. The default is "----------------------------------------." This is optional.

Name

The name of the trace listener. The default is FlatFile Trace Listener. This is required.

Trace Output Options

Trace listeners that do not output to a text formatter use this property to determine which options, or elements, should be included in the trace output. Possible values are: CallStack, DateTime, LogicalOperationStack, None, ProcessId, ThreadId, and Timestamp. The default is None. For an explanation of these values, see TraceOutputOptions Values. This is optional.

Note

If the file you specify for the Flat FileTraceListener is read-only, the trace listener does not write the data to the file and no exception occurs. Make sure that the file attributes are set to read/write.

When you use the FlatFileTraceListener class to write log information to a file, the block locks the file until the application closes. It is possible to open and read the file, but you cannot move or delete the log file until you close the application.

Event Log Trace Listener

The following table lists the properties that you can set when you add an event log trace listener.

Property

Description

Severity Filter

Applies a filter that selects the level of message that it will detect. The valid values are All (the default), Off, Critical, Error, Warning, Information, Verbose, and ActivityTracing. The setting effectively means "the specified level and everything more important." For example, the Warning setting will detect warnings, errors, and critical events.

Formatter Name

The formatter to use with this trace listener. Select one from the drop-down list. The default isnone. This is optional.

Log Name

The name of the event log where entries are written. The default is Application. This is optional.

Machine Name

The name of the computer on which to write log entries. This is optional.

Name

The name of the trace listener. The default is Event Log Trace Listener. This is required.

Source Name

The source name to use when writing to the log. The default is Enterprise Library Logging. This is required.

Trace Output Options

Trace listeners that do not output to a text formatter use this property to determine which options, or elements, should be included in the trace output. Possible values are: CallStack, DateTime, LogicalOperationStack, None, ProcessId, ThreadId, and Timestamp. The default is None. For an explanation of these values, see TraceOutputOptions Values. This is optional.

Message Queuing Trace Listener

The following table lists the properties that you can set when you add a Message Queuing (MSMQ) Trace Listener.

Property

Description

Severity Filter

Applies a filter that selects the level of message that it will detect. The valid values are All (the default), Off, Critical, Error, Warning, Information, Verbose, and ActivityTracing. The setting effectively means "the specified level and everything more important." For example, the Warning setting will detect warnings, errors, and critical events.

Formatter Name

The formatter to use with this trace listener. Select one from the drop-down list. This must be the binary formatter when you use this listener with the message queuing distributor service. This is optional.

Message Priority

Sets the priority of a log entry. This determines its priority while the log entry is in transit and when it is inserted into its destination queue. Possible values are AboveNormal, High, Highest, Low, Lowest, Normal, VeryHigh, and VeryLow. It applies to the MsmqTraceListener class. The default is Normal. This is optional.

Name

The name of the trace listener. The default is Message Queuing Trace Listener.

Queue Path

The path to the queue that the Msmq TraceListener instance uses. This attribute is a message queuing path, and it applies to the MsmqTraceListener class. The default is .\Private$\myQueue. This is required.

Recoverable

Specifies whether the log entry is guaranteed to be delivered if there is a computer failure or network problem. The default is False. This is optional.

Time To Be Received

The total time for a log entry to be received by the destination queue. The default is 49710.06:28:15. This is optional.

Time To Reach Queue

The maximum time for the log entry to reach the queue. The default is 49710.06:28:15. This is optional.

Trace Output Options

Attaches additional information to platform-provided trace listener output for listeners that do not output to a text formatter. Possible values are CallStack, DateTime, LogicalOperationStack, None, ProcessId, ThreadId, and Timestamp. The default is None. For an explanation of these values, see TraceOutputOptions Values. This is optional.

Transaction Type

The type of a Message Queuing transaction. Possible values are Automatic, None, and Single. It applies to the MsmqTraceListener class. The default is None. This is optional.

Use Authentication

Specifies whether the message was (or must be) authenticated before being sent. The default is False. This is optional.

Use Dead Letter Queue

Specifies whether a copy of a message that could not be delivered should be sent to a dead-letter queue. The default is False. This is optional.

Use Encryption

Specifies whether to make the message private. The default is False. This is optional.

Rolling Flat File Trace Listener

The following table lists the properties that you can set when you add a rolling flat file trace listener. This trace listener allows you to control the size and age of a log file.

Property

Description

File Name

This is the name of the rolling flat file. This is a required value. It can include environment variables such as %WINDIR%, %TEMP%, and %USERPROFILE%. If you also set the Max Archived Files property, See the advice on choosing a file name in the following Remarks section.

Severity Filter

Applies a filter that selects the level of message that it will detect. The valid values are All (the default), Off, Critical, Error, Warning, Information, Verbose, and ActivityTracing. The setting effectively means "the specified level and everything more important." For example, the Warning setting will detect warnings, errors, and critical events.

Message Footer

Additional information contained in the file footer. The default is "----------------------------------------." This is optional.

Formatter Name

The formatter to use with this trace listener. Select one from the drop-down list. The default is none. This is optional.

Message Header

Additional information contained in the file header. The default is "----------------------------------------." This is optional.

Max Archived Files

The maximum number of log files to retain. When set to an integer value, the trace listener will purge old files based on the file creation date when the number exceeds the specified value. See the note in the following Remarks section if you set this property.

Name

This is the name of the trace listener. The default is Rolling Flat File Trace Listener. This is required.

File Exists Behavior

This property determines what occurs to an existing file when it rolls over. If you select Increment, the application block creates a new file and names it by incrementing the timestamp. If you select Overwrite and do not provide a value for the Timestamp Pattern property, the existing file is overwritten.

Roll Interval

This property determines when the log file rolls over. You can select None (the default), Midnight (in which case the log will roll over at midnight), Minute, Hour, Day, Month, Week, or Year. This is optional.

Roll Size KB

This is the maximum size the file can reach, in kilobytes, before it rolls over. This is optional.

Timestamp Pattern

This is the date/time format that is appended to the new file name (see the Remarks section that follows this table).

Trace Output Options

Trace listeners that do not output to a text formatter use this property to determine which options, or elements, should be included in the trace output. Possible values are: CallStack, DateTime, LogicalOperationStack, None, ProcessId, ThreadId, and Timestamp. The default is None. For an explanation of these values, see TraceOutputOptions Values. This is optional.

Remarks

  • If you set the Max Archived Files property, this trace listener will delete (purge) files using the file name pattern **[file-name] *.**file-extension. Therefore, it will delete all log files for any trace listener that matches this pattern when it purges archived log files. To prevent this, use a value for the File Name property that included an additional period. For example, use **[file-name] .[additional-name].**file-extension.
  • You can control either the size of the file, its age, or both. For example, if you specify in configuration a Roll Size KB value of 5 KB and a Roll Interval value of Day, the file rolls when its size exceeds 5 KB and it also rolls at the end of the day.
  • If you select Increment for the File Exists Behavior, the application block creates a new file when the existing file rolls over. The file name includes the current timestamp. If a file with this name already exists, the application block adds an integer to the end of the timestamp and increments it until it cannot find a file with that name. For example, assume there is a file named mylog2007-01-10.log and the file rolls over while that timestamp is still valid. The Logging Application Block will then look for a file named mylog2007-01-10.1.log. If no such file exists, it will use that file name for the new file. If that file also exists, it will then attempt to locate the log with the next sequence number mylog2007-01-10.2.log.
  • If you select Overwrite for the File Exists Behavior, the application block replaces the existing file with a new file when the current file rolls over. However, if you also set the Timestamp Pattern property, the application block will create a new file with the current time stamp instead of replacing the existing file. If, for some reason, it cannot overwrite the file, it will generate a name using the same process that is used with the Increment value.
  • Relative path names resolve to a location that is relative to the AppDomain.CurrentDomain.BaseDirectory directory.

System Diagnostics Trace Listener

The TraceListener class provides the abstract base class for trace listeners that monitor trace and debug output. The following table lists the properties that appear when you add a System DiagnosticsTrace Listener.

Property

Description

InitData

If supplied, this property is used when the application block constructs a trace listener. It is a string whose meaning depends on the type of trace listener being constructed. For the .NET Framework trace listeners, the string has the following values: TextWriterTraceListener: filename; XmlWriterListener: filename; DelimitedLIstTraceListener: filename; ConsoleTraceListener: not applicable; DefaultTraceListener: not applicable; EventLogTraceListener: event source name. If the InitData field is not specified, the block uses the default constructor. If the user specifies the InitData field for a trace listener that does not have a constructor overload that accepts a string, an error occurs. This is optional.

Name

The name of the trace listener. The default is System Diagnostics Trace Listener. This is required.

Severity Filter

Applies a filter that selects the level of message that it will detect. The valid values are All (the default), Off, Critical, Error, Warning, Information, Verbose, and ActivityTracing. The setting effectively means "the specified level and everything more important." For example, the Warning setting will detect warnings, errors, and critical events.

Trace Output Options

Trace listeners that do not output to a text formatter use this property to determine which options, or elements, should be included in the trace output. Possible values are: CallStack, DateTime, LogicalOperationStack, None, ProcessId, ThreadId, and Timestamp. The default is None. For an explanation of these values, see TraceOutputOptions Values. This is optional.

Type Name

The type of the trace listener. Select by clicking the ellipsis button (...). This opens the Type Selector. This is required.

Note

If you specify a System Diagnostics trace listener that writes to a file and that file is read-only, the trace listener does not write the data to the file and no exception occurs. Make sure the file attributes are set to read/write.

WMI Trace Listener

The WMI trace listeneris atrace listener that raises a WMI management event for each log entry it receives. The following table lists the properties that you can set when you add a WMI Trace Listener.

Property

Description

Severity Filter

Applies a filter that selects the level of message that it will detect. The valid values are All (the default), Off, Critical, Error, Warning, Information, Verbose, and ActivityTracing. The setting effectively means "the specified level and everything more important." For example, the Warning setting will detect warnings, errors, and critical events.

Name

The name of the trace listener. The default is WMI Trace Listener. This is required.

Trace Output Options

Trace listeners that do not output to a text formatter use this property to determine which options, or elements, should be included in the trace output. Possible values are: CallStack, DateTime, LogicalOperationStack, None, ProcessId, ThreadId, and Timestamp. The default is None. For an explanation of these values, see TraceOutputOptions Values. This is optional.

XML Trace Listener

The following table lists the properties that you can set when you add an XML Trace Listener.

Property

Description

File Name

This is the name of the file where the trace listener writes the data it extracts from an XmlLogEntry object. This is a required value. It can include environment variables such as %WINDIR%, %TEMP%, and %USERPROFILE%.

Severity Filter

Applies a filter that selects the level of message that it will detect. The valid values are All (the default), Off, Critical, Error, Warning, Information, Verbose, and ActivityTracing. The setting effectively means "the specified level and everything more important." For example, the Warning setting will detect warnings, errors, and critical events.

Name

This is the name of the trace listener. The default is XML Trace Listener. This is required.

Trace Output Options

Trace listeners that do not output to a text formatter use this property to determine which options, or elements, should be included in the trace output. Possible values are: CallStack, DateTime, LogicalOperationStack, None, ProcessId, ThreadId, and Timestamp. The default is None. For an explanation of these values, see TraceOutputOptions Values. This is optional.