Using the trace event service for the out-of-process scenario
.png "patterns & practices Developer Center")
To collect and process the log messages from an application in the out-of-process scenario you can use the Semantic Logging Out-of-Process Windows Service/Console Host (SemanticLogging-svc.exe). The Out-of-Process Host implements a TraceEventService instance that collects and processes trace messages from your application.
To use the Out-of-Process Host, after you have created your custom event source within your application and added the code required to raise the events, you must:
- Obtain and install the Out-of-Process Host from NuGet or CodePlex. For more details, see Installing and running the Out-of-Process Windows Service/Console Host.
- Decide if you want to run the Out-of-Process Host as an application or as a service. For more details, see Running the Out-of-Process Host as an application or a service.
- Configure the Out-of-Process Host using an XML file. For more details, see Configuring the Out-of-Process Host.
- Ensure that the Out-of-Process Host has successfully initialized its trace sessions with ETW and is collecting events. For more details, see Verifying that the Out-of-Process Host has successfully initialized.
- Decide if, and how, you will collect events from multiple processes. For more details, see Collecting events from multiple processes.
As an alternative to the Out-of-Process Host application included with the block, you could configure ETW to save the trace messages to an .etl file and use another tool to read this log file. However, the Out-of-Process Host application offers more choices of where to persist the log messages.
Running the Out-of-Process Host as an application or a service
You can run the Out-of-Process Host as a console application or as a Windows service. Typically, you will run the Out-of-Process Host as a console application only when you are developing and testing your logging strategy. It’s convenient to be able to stop and start the application, and use a Console sink to view any log messages in a console window.
In a production environment, you should run the Out-of-Process Host as a Windows service. In this scenario, you are unlikely to want to see log messages as they are processed in a console window. More likely, you will want to save the log messages to a file, database, or some other persistent storage. You can easily configure the Out-of-Process Host to start as a Windows service when the operating system starts.
The account that the service runs under must have read permission for the configuration file.
Configuring the Out-of-Process Host
The Out-of-Process Host uses configuration information from an XML file to determine which event sources to collect trace messages from, and which sinks and formatters to use to process those messages. The default name for the configuration file is SemanticLogging-svc.xml, though you can change this by editing the EtwConfigurationFileName key as described in the section Editing the Out-of-Process Host app.config file. When you edit the configuration file in Visual Studio, you can use the supplied schema file (SemanticLogging-svc.xsd) to provide IntelliSense support in the editor.
You must edit the configuration file to specify the sinks and formatters you want to use to process the trace messages from your application. You also add details to the configuration file of the event sources in your application. You must ensure that the names of the event sources in the configuration file match the names of the event sources as specified by the EventSource attribute in your custom event source classes (if the EventSource attribute is not present, use the name of your event source class).
The following is an example configuration file that defines how the Out-of-Process Host should collect trace messages created by another application that uses the event source named MyCompany. This example uses three sinks to write log messages to three different destinations. Each sink is configured to log messages with different severity levels. Additionally, the Console sink filters only messages that have the Diagnostics or Perf keywords (the Diagnostics constant has a value of four and the Perf constant has a value of eight in the nested Keywords class in the event source class).
<?xml version="1.0"?>
<configuration
xmlns=https://schemas.microsoft.com/practices/2013/entlib/semanticlogging/etw
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xsi:schemaLocation="https://schemas.microsoft.com/practices/2013/entlib/
semanticlogging/etw SemanticLogging-svc.xsd">
<!-- Optional settings for this host. -->
<traceEventService/>
<!-- Event sink definitions used by this host to listen
for ETW events emitted by these EventSource instances. -->
<sinks>
<consoleSink name="ConsoleEventSink">
<sources>
<eventSource name="MyCompany" level="LogAlways" matchAnyKeyword="12"/>
</sources>
<eventTextFormatter header="+=========================================+"/>
</consoleSink>
<rollingFlatFileSink name="RollingFlatFileSink"
fileName="RollingFlatFile.log"
timeStampPattern="yyyy"
rollFileExistsBehavior="Overwrite"
rollInterval="Day">
<sources>
<eventSource name="MyCompany" level="Error"/>
</sources>
</rollingFlatFileSink>
<sqlDatabaseSink name="SQL Database Sink"
instanceName="Demo"
connectionString="Data Source=(localDB)\v11.0;
Initial Catalog=Logging;
Integrated Security=True">
<sources>
<eventSource name="MyCompany" level="Warning"/>
</sources>
</sqlDatabaseSink>
</sinks>
</configuration>
A full reference to the schema for configuring the Out-of-Process Host is included in the topic Configuration schema for the out-of-process model of this guide.
If the block detects any errors when it loads the configuration, it will generate a log event and continue to process the remainder of the configuration file. If you are running the Out-of-Process Host as a Windows service, it writes these error messages to the Windows Application Event Log from the source “Enterprise Library Semantic Logging Service.” If you are running the Out-of-Process Host application as a console application, the application displays these messages in the console window.
Dynamic reconfiguration
By default, the Out-of-Process Host reads its configuration from a file named SemanticLogging-svc.xml. It reads this file at start up, and then continues to monitor this file for changes. You can start the Out-of-Process Host application without any event sources, event listeners, sinks, or formatters defined in the configuration file, and add them as you develop your logging strategy.
If you make any changes to the traceEventService element, this will cause the service to recycle with the possibility that some messages will be lost while the service is restarting. If you make any other changes, such as to sink or formatter definitions, the service will reconfigure itself without recycling.
If the block detects an invalid configuration file, it will continue to use the existing settings and log the error TraceEventServiceReconfigurationFault. It logs a successful reconfiguration using the TraceEventServiceReconfigurationChanged message.
Editing the Out-of-Process Host app.config file
You can use the app.config file for the Out-of-Process Host to change the following settings:
- You can change the name and location of the XML configuration file for the Semantic Logging Application Block by editing the EtwConfigurationFileName setting.
- You can change the log filter level for non-transient errors raised by the Out-of-Process Host and logged in the Windows Event Log by adding or editing the NonTransientErrorsEventLevel setting. It must be set to one of the values from the System.Diagnostics.Tracing.EventLevel enumeration. The default value is LogAlways.
The following XML sample from the app.config file shows these settings.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<appSettings>
<add key="EtwConfigurationFileName" value="SemanticLogging-svc.xml"/>
<add key="NonTransientErrorsEventLevel" value="Error"/>
</appSettings>
...
</configuration>
Verifying that the Out-of-Process Host has successfully initialized
To verify that the Out-of-Process Host has been successfully initialized you can use the Performance Monitor utility in Windows. When the Out-of-Process Host is running, it registers Event Trace Sessions with names prefixed, by default, with Microsoft-SemanticLogging-Etw-. Each session might be monitoring several event sources. The full name of each session includes the name of the sink. You can view these sessions in the Performance Monitor utility in Windows.
Note
You can change the default prefix for the session name and the sink names in the SemanticLogging-svc.xml file.
To view the event trace sessions created by the Semantic Logging Application Block
- Start the Performance Monitor utility in Windows.
- Expand the Data Collector Sets node and then select Event Trace Sessions.
- Check that an event trace session named Microsoft-SemanticLogging-Etw-*your sink name*****exists for each sink defined in the configuration file. If you have changed the default session prefix, you should see a name with that prefix instead.
- You can examine the properties of each session by choosing Properties from the context menu.
When the Out-of-Process Host application terminates, these trace sessions are automatically removed. These sessions might remain if the host process crashes, but they will be recreated when the process restarts.
For more information, see the topic Event Tracing Sessions on MSDN.
Collecting events from multiple processes
A single instance of the Out-of-Process Host can collect messages from multiple event sources in multiple applications. You can also run multiple instances of the Out-of-Process Host, but each instance must use a unique session name. You specify the session name in the SemanticLogging-svc.xml configuration file as part of the settings for the trace event service in the Out-of-Process Host.
Depending on the resources available, there may be a limit on the number of ETW sessions that you can create on a computer. The block will log an error if it cannot create sessions for all of the sinks defined in your configuration file.
If you use the same custom event source class in multiple applications, it is possible that you will modify this in one of the applications creating event messages. If you do not change the event source name or identifier using the attributes in the event source class, the changes will be picked up by the out-of-process host without it restarting.
The trace event service in the Out-of-Process Host automatically manages updates to event source manifests, and it will always use the highest version. Therefore, you should add version information to your event source classes, and ensure that changes are only additive, in order to avoid affecting the logging behavior of the other applications.