Configuration schema for the out-of-process model

Article
07/30/2014

When used out-of-process, you must configure the Semantic Logging Application Block by using an XML configuration file in the runtime folder of the Out-Of-Process Host application or service. Figure 1 shows a high-level schematic view of the schema of this configuration file.

Figure 1 - A schematic view of the schema for the out-of-process configuration file

Figure 1 - A schematic view of the schema for the out-of-process configuration file

The following sections describe the elements shown in Figure 1 and the attributes for each one:

configuration element
traceEventService element
sinks element
consoleSink element
customSink element
flatFileSink element
rollingFlatFileSink element
sqlDatabaseSink element
windowsAzureTableSink element
sources element
eventSource element
arguments element
filter element
Formatter elements
customEventTextFormatter element
jsonEventTextFormatter element
textEventTextFormatter element
xmlEventTextFormatter element

configuration element

This is the top-level element in the configuration file. This is a required element. This element has two child elements and no attributes. The following table lists the child elements of the configuration element.

Child element	Description
traceEventService	Contains custom settings for the trace event service. This element is optional.
sinks	Contains zero or more elements that specify the sinks that determine where the trace event service will save trace messages. This element is optional but, if it is not included, the out-of-process host application will not collect or process any trace messages.

traceEventService element

The traceEventService element enables you to override the default settings for the trace event service. This element is optional. This element has no child elements. The following table lists the attributes for the traceEventService element.

Attribute	Description
sessionNamePrefix	The prefix for the name of the trace event session. The maximum length is 200 characters. The full name of the ETW session is the value of this sessionNamePrefix attribute concatenated with the name of the sink. If not specified, the prefix of the session name is Microsoft-SemanticLogging-Etw.

sinks element

The elements in the top-level sinks element define the sinks used by the trace event service. The sinks element must contain at least one child element that is the name of a sink. The available sink elements are:

consoleSink element
customSink element
flatFileSink element
rollingFlatFileSink element
sqlDatabaseSink element
windowsAzureTableSink element

consoleSink element

This element specifies an instance of the Console event sink. It has a single sources child element. The following table lists the attributes of the consoleSink element.

Attribute	Description
name	The name of the sink. The maximum length is 200 characters. This is a required attribute.
colorMapperType	The type name of the color mapper to use with this sink. This is an optional attribute. The default if omitted is none.

customSink element

This element specifies an instance of a custom event sink. It has a single parameters child element that contains a list of parameters for this sink. The following table lists the attributes of the customSink element.

Attribute	Description
name	The name of the custom sink. The maximum length is 200 characters. This is a required attribute.
type	The full type name of the custom sink. This is a required attribute.

For more information about using the customSink element, see the topic Creating a custom event sink.

parameters and parameter elements

The parameters element contains one or more parameter elements. Each parameter element has name, type, and value attributes, and optionally contains a nested parameters element.

flatFileSink element

This element specifies an instance of the Flat File event sink. It has a single sources child element. The following table lists the attributes of the flatFileSink element.

Attribute	Description
name	The name of the sink. The maximum length is 200 characters. This is a required attribute.
fileName	The unique name for the file to use for writing trace messages. Each sink instance should write to a separate file. This is a required attribute.

rollingFlatFileSink element

This element specifies an instance of the Rolling Flat File****sink. It has a single sources child element. The following table lists the attributes of the rollingFlatFileSink element.

Attribute	Description
name	The name of the sink. The maximum length is 200 characters. This is a required attribute.
fileName	The unique name for the file to use for writing trace messages. Each sink instance should write to a separate file. This is a required attribute.
rollSizeKB	This is the maximum size the file can reach, in kilobytes, before it rolls over. This is an optional attribute.
timeStampPattern	This is the date/time format used for the date information appended to the new file name. This is an optional attribute. See the notes in the topic Rolling Flat File event sink for more details about the behavior of this setting.
rollFileExistsBehavior	This property determines what happens 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. This is an optional attribute.
rollInterval	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 an optional attribute.
maxArchivedFiles	The maximum number of log files to retain. When set to an integer value, the sink will purge old files based on the file creation date when the number exceeds the specified value. This is an optional attribute. See the notes in the topic Rolling Flat File event sink for more details about the behavior of this setting.

sqlDatabaseSink element

This element specifies an instance of the SQL Database sink. It has a single sources child element. The following table lists the attributes of the sqlDatabaseSink element. See the notes in the topic SQL Database event sink for more details about using this sink.

Attribute	Description
Name	The name of the sink. The maximum length is 200 characters. This is a required attribute.
instanceName	The name of the instance originating the log entries. This is a required attribute.
connectionString	The connection string for the target database for log messages. This is a required attribute.
tableName	The name of the database table that will store the log entries. This is an optional attribute. If omitted, the default value is Traces.
bufferingIntervalInSeconds	The frequency at which the sink writes the accumulated log messages to the SQL Server database. If set to zero, the sink does not buffer messages but writes each message directly to the database table. This is an optional attribute; the default value is 30 seconds.
bufferingCount	The number of log messages the sink will accumulate in the buffer before it writes them to the database table. This is an optional attribute; the default value is 1000 log messages.
maxBufferSize	Defines the maximum number of entries that can be buffered while the sink is sending to the database before it starts dropping entries. This is an optional attribute; the default value is 30,000 entries.
bufferingFlushAllTimeoutInSeconds	Defines a timeout interval for flushing the entries when the service is shut down. If the timeout period elapses before all entries have been sent to the database, some will be lost. This is an optional attribute; the default value is five seconds. A value of -1 specifies an infinite timeout.

windowsAzureTableSink element

This element specifies an instance of the Azure Table Storage sink. It has a single sources child element. The following table lists the attributes of the windowsAzureTableSink element. See the notes in the topic Azure Table Storage event sink for more details about using this sink.

Attribute	Description
Name	The name of the sink. The maximum length is 200 characters. This is a required attribute.
instanceName	The name of the instance originating the log entries. This name must be unique for each instance of the application. This is a required attribute.
connectionString	The connection string for the Azure storage account you are using. This is a required attribute.
tableAddress	The name of the table you will write log messages to. This is an optional attribute. If omitted the default value is SLABLogsTable.
sortKeysAscending	Controls the sort order of the log messages in the table. This is an optional attribute. The default value is true.
bufferingIntervalInSeconds	The frequency at which the sink writes the accumulated log messages to Azure storage. If set to zero, the sink does not buffer messages but writes each message directly to the log file. This is an optional attribute; the default value is ten seconds.
maxBufferSize	Defines the maximum number of entries that can be buffered while the sink is sending entries to Azure storage before it starts dropping entries. This is an optional attribute; the default value is 30,000 entries.
bufferingFlushAllTimeoutInSeconds	Defines a timeout interval for flushing the entries when the service is shut down. If the timeout period elapses before all entries have been sent to Azure storage, some will be lost. This is an optional attribute; the default value is five seconds. A value of -1 specifies an infinite timeout.

sources element

Each sink element contains a sources element that lists all of the event sources from which the sink receives trace messages. The event sources are defined in one or more eventSource child elements.

eventSource element

Each eventSource element specifies an event source from which the sink can receive trace messages. The following table lists the child elements of the eventSource element.

Child element	Description
arguments	This element contains a list of arguments in the form of key/value pairs that are passed to the EventSource implementation. This element is optional. See arguments element for more information.
filter	This element contains a list of processes from which events will be collected. This element is optional. See filter element for more information.

The following table lists the attributes of the eventSource element.

Attribute	Description
name	The name of the event source from which to receive trace messages. This value should match the Name property of the EventSource attribute in your event source class. If the class does not contain the EventSource attribute, use the class name. This is an optional attribute. See the notes that follow this table.
id	The GUID of the event source from which to receive trace messages. This is an optional attribute. See the notes that follow this table. If this is not supplied, the system will determine the correct GUID to use.
level	Specifies the lowest level of messages that must be logged. The value is one of LogAlways, Critical, Error, Warning, Informational, and Verbose. This is an optional attribute. The default value is LogAlways.
matchAnyKeyword	A long value that identifies the keyword(s) from the EventSource to match. This value is treated as a bitvector to enable you to match on multiple keywords. The default value is zero, which matches all keywords.

Notes

You should provide either the name or the id attribute but not both.

Given the following keyword definitions in an EventSource implementation:

[EventSource(Name = "MyCompany")]
  public class MyCompanyEventSource : EventSource
  {
    public class Keywords
    {
      public const EventKeywords Page = (EventKeywords)1;
      public const EventKeywords DataBase = (EventKeywords)2;
      public const EventKeywords Diagnostic = (EventKeywords)4;
      public const EventKeywords Perf = (EventKeywords)8;
    }
    ...
}

If you set the value of the matchAnyKeyword attribute to four, the event listener will capture log messages with the Diagnostic keyword. If you set the value of the matchAnyKeyword attribute to five, the event listener will capture log messages with the Page or Diagnostic keyword.

arguments element

This element can be used in conjunction with the filter element to sample and filter events received by the Out-of-Process Host. The arguments element contains a list of arguments in the form of one or more add elements, each containing key/value pairs that represent one argument key/value pair that will be passed to the EventSource implementation. This element is optional, and can occur only once.

The EventSource class accepts a range of arguments that control its behavior. For more information about the supported arguments, see Sampling and filtering events.

This element can be used in conjunction with the arguments element to sample and filter events received by the Out-of-Process Host. The filter element is optional, and can occur only once.

The filter element contains one or more process child elements that specify the processes from which events will be collected. Each process element contains only a name attribute that specifies the name of the process to filter.

For more information about using the filter element, see Sampling and filtering events.

Formatter elements

The sink elements flatFileSink, rollingFlatFileSink, consoleSink, and customSink can contain a single nested formatter element. The available formatter elements are:

customEventTextFormatter element
jsonEventTextFormatter element
textEventTextFormatter element
xmlEventTextFormatter element

customEventTextFormatter element

This element specifies an instance of a custom event text formatter. It has a single parameters child element that contains a list of parameters for this formatter. The following table lists the attributes of the customEventTextFormatter element.

Attribute	Description
type	The full type name of the custom formatter. This is a required attribute.

For information about creating custom event text formatters, see Creating a custom event formatter.

jsonEventTextFormatter element

This element specifies an instance of the JSON event text formatter. It has no child elements. The following table lists the attributes of the jsonEventTextFormatter element.

Attribute	Description
formatting	Either None or Indented. This controls the layout of the JSON in the output. This is an optional attribute. The default value is None.
dateTimeFormat	The format of the timestamp written to the log. By default, the block uses “O” as the format string. For more information, see Standard Date and Time Format Strings on MSDN. This is an optional attribute.
includeEntrySeparator	Set this to true to include a comma separator between event entries in the sink destination.

textEventTextFormatter element

This element specifies an instance of the standard event text formatter. It has no child elements. The following table lists the attributes of the textEventTextFormatter element.

Attribute	Description
header	A string to appear before the log message. This is an optional attribute.
footer	A string to appear after the log message. This is an optional attribute.
verbosityThreshold	An event level as defined in the EventLevel enumeration: one of Verbose (5), Informational (4), Warning (3), Error (2), Critical (1), or LogAlways (0). All log messages with an event level equal to or lower than this value are displayed in detail. Other log messages are displayed in summary. This is an optional attribute. The default value is LogAlways.
dateTimeFormat	The format of the timestamp written to the log. By default, the block uses “O” as the format string. For more information, see Standard Date and Time Format Strings on MSDN. This is an optional attribute.

xmlEventTextFormatter element

This element specifies an instance of the XML event text formatter. It has no child elements. The following table lists the attributes of the xmlEventTextFormatter element.

Attribute	Description
formatting	Either None or Indented. This controls the layout of the XML in the output. This is an optional attribute. The default value is None.
dateTimeFormat	The format of the timestamp written to the log. By default, the block uses “O” as the format string. For more information, see Standard Date and Time Format Strings on MSDN. This is an optional attribute.

This formatter generates XML that complies with the ETW Event Schema.

Next Topic | Previous Topic | Home | Community

Share via