Semantic Logging 2.0 - July 2014

Semantic Logging can help you to take advantage of comprehensive and informative logging functionality in most types of applications and scenarios. By using the Semantic Logging Application Block, you can quickly and more easily incorporate structured events that conform to known schemas into your applications, and store the information they contain in a variety of logging destinations. This makes it easier to consume logging information—especially when there is a large volume of log data.

Downloads	Via NuGet (inside Visual Studio, use the NuGet package manager and search for "Semantic Logging") Out-of-process service
Release Notes	Release Notes
Class Library	Class Library
Support	http://slab.codeplex.com/discussions
Community	http://slab.codeplex.com/
Community Extensions	https://slab.codeplex.com/wikipage?title=Community%20Sinks
Feedback and Issue Reporting	http://slab.codeplex.com/workitem/list/basic
Videos	Creating Structured and Meaningful Logs with Semantic Logging
License	Apache License, Version 2.0

Common scenarios

The Semantic Logging Application Block is a framework for capturing and manipulating events raised by applications, and storing the typed and structured information they contain in log files or other logging stores. It takes advantage of features of the .NET Framework (version 4.5 and above) and Event Tracing for Windows (ETW). ETW is a fast, lightweight, strongly typed, extensible logging system that is built into the Windows operating system.

The Semantic Logging Application Block consumes events raised by event sources, and provides features to help you sample, filter, correlate, format, and store these events in a wide range of target logging stores. The block can be used both in-process within your applications, or out-of-process to capture events generated by one or more processes.

Using the Semantic Logging Application Block with your own custom event sources provides the following advantages:

• You can more easily abstract the process of creating events from the process of storing these events, allowing you to easily adapt your logging strategy to meet changing requirements.
• You can more easily write code to consistently raise events within your applications.
• You can more easily implement a consistent approach for capturing and filtering events, and storing them in a database, a text file, Microsoft Azure table storage, or other locations.
• You can more easily query and analyze log files because they have a consistent structure and contain typed information.
• You can more easily capture, correlate, and consolidate log messages from multiple sources, including asynchronous tasks.

Audience requirements

These reusable components and guidance are intended primarily for software developers and software architects developing enterprise applications as well as IT professionals and system administrators managing these applications. To get the greatest benefit from this guidance, developers and architects should have an understanding of the following technologies:

• Microsoft Visual C# or Microsoft Visual Basic
• Microsoft .NET Framework

Contents of this release

The Semantic Logging Application Block contains the following:

• Binaries (pre-compiled, strong-named assemblies for all the source code)
• Source code****
• Symbols for debugging
• Unit tests****

What’s New

This major release of the Semantic Logging Application Block has some potentially breaking changes:

• All sources now expose IObservable<EventEntry> event streams instead of sink-specific representations.
• All sinks now expose the ProcessId and ThreadId properties. If the application is running in full trust mode, values are captured and stored in all logging destinations.
• Process filters now enable you get events from only specific processes, specified by name. Support for configuring sampling and using process filters is now available when using the out of process approach under version 4.5.1 of the .NET Framework. Sampling is configured using a general-purpose key/value pair collection using the same key and value conventions as use for the in-process approach.
• Compatibility with the NuGet EventSource package has been improved. The application block source must be updated and rebuilt to work with the latest EventSource package, which supports channels but does not support sampling. All projects contain a reference to the NuGet EventSource package.
• System.Diagnostics.Tracing has been changed to Microsoft.Diagnostics.Tracing in all source files.
• A constant named EVENT_SOURCE_PACKAGE is defined in the unit tests project in order to disable tests that cannot run using the NuGet EventSource package.
• StyleCop integration has been improved.
• Notification for out-of-band events has been added. Events with identifier 0 are not part of the manifest for an EventSource. Instead, they are used to communicate with the consumer of the events. Notification has been enabled for these by adding a new event with identifier 811 that the application block will raise.
• Consuming ETW events requires access to the Performance* group. The Out-of-Process Host service can now be installed under an account other than Local Service, avoiding the requirement to include the Local Service account in the Performance* group.
• Sinks and the EventSourceAnalyzer class have been moved into separate NuGet packages.
• The ElasticSearch sink is no longer maintained by patterns and practices. It is now a community project available through the CodePlex community site.

System requirements

• Windows 7 Professional, Windows 8, or higher, 32-bit and 64-bit; or Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, or higher.

For a rich development environment, the following is recommended:

• Microsoft Visual Studio 2012 or higher.

Getting started

• Install the application block components into a Visual Studio project using NuGet, or download the packages directly from NuGet (see the table at the start of this topic).
• Download the Out-of-Process Host from CodePlex, or install it using NuGet (see the table at the start of this topic).
• Read the introduction to the application block and the key scenarios provided in this guidance. The key scenarios include logging events to the console, a disk file, a database, and Azure table storage; correlating events, and sampling and filtering events.

This guide explores the following topics to help you understand how you can use the Semantic Logging Application Block in your applications:

• Overview of the Semantic Logging Application Block. This topic explains in simple terms what the block does, how it works, and the ways you can use it in your applications.
• Developing applications using the Semantic Logging Application Block. This section of the guide contains topics that explain how to use the Semantic Logging Application Block in your applications. It describes the key scenarios, the steps required to use the block, and shows how to configure the block to perform common tasks.
• Extending the Semantic Logging Application Block. This section of the guide explains how to extend the application block by creating your own custom event sinks, log formatters, log filters, and trace event host applications that collect events.
• Deployment and operations. This section of the guide contains performance and security information related to deploying and administering the block, the full configuration schema for the Out-of-Process Host, and details of the instrumentation within the block.
• Design of the Semantic Logging Application Block. This topic explains the decisions that went into designing the application block, and the rationale behind those decisions.

Community

The Semantic Logging Application Block, like many patterns & practices deliverables, is associated with a community site: http://slab.codeplex.com/. On this community site, you can provide feedback and connect with other users to share ideas. You can post questions and get support using the forum. You can also download additional content, such as extensions and training material. Community members can also help Microsoft plan and test future releases. Community-developed extensions to the Semantic Logging Application Block are available on the EntLib Contrib site.

Feedback and support

Questions? Comments? Suggestions? To provide feedback about this release, or to get help with any problems, please visit the community site at http://slab.codeplex.com/. This is the preferred feedback and support channel because it allows you to share your ideas, questions, and solutions with the entire community. The Semantic Logging Application Block is a guidance offering, designed to be reused, customized, and extended. Code-based guidance is shipped "as is" and without warranties. Customers can obtain support through Microsoft Premier Support Services for a fee, but the code is considered user-written by Microsoft support staff.

Authors and contributors

The Semantic Logging Application Block 2.0 was produced by the following individuals:

• Product/Program Management: Christopher Bennage and David Hsu.
• Architecture/Development: Fernando Simonazzi, Randy Levy, and Mani Subramanian.
• Testing: Mani Subramanian, Carlos Farre, and Veerapat Sriarunrungrueang.
• Documentation: Alex Homer.
• Editing and production: RoAnn Corbisier and Nelly Delgado.

Many thanks to our advisors on this release: Vance Morrison, Cosmin Radu, Trent Swanson, Grigori Melnik, and Julian Dominguez.

More Information

For more information about using ETW and event sources, see:

• Event Tracing on the Windows Developer Center website
• The EventSource Class reference in the MSDN library
• Improve Debugging And Performance Tuning With ETW in MSDN Magazine
• Posts tagged “eventsource” on Vance Morrison's blog

For more information about logging, and managing other crosscutting concerns, see the following guides:

• Microsoft Application Architecture Guide, 2nd Edition
• Design Guidelines for Exceptions

Related resources

• Microsoft patterns & practices Developer Center
• Microsoft Enterprise Library home page
• Microsoft patterns & practices cloud development guidance

Next Topic | Community