Microsoft.Diagnostics.Tracing.EventSource is now stable

Microsoft.Diagnostics.Tracing.EventSource is now stable

Rate This
  • Comments 14

We are announcing the RTM of the EventSource NuGet package, which enables fast app tracing to the Windows Event Log, including in production. This post was written by Cosmin Radu, a software developer on the .NET Runtime team.

Over the past several weeks we’ve been working on addressing some feedback we’ve received from our users and added some improvements, including support for .NET Framework 3.5. Today I’m happy to announce the stable release of the EventSource and the EventRegister packages.

NEW: EventSource Supports .NET 3.5

With the RTM release, the NuGet package now supports projects running against version 3.5 of the .NET Framework.

NEW: EventSource Improved Code Sharing

With the RTM release we’ve relaxed some of the event source validation rules in order to enable certain advanced usage scenarios. While the new support will not be needed for a majority of situations, it will help out integrating your new event sources into existing logging systems, or allow you to more easily share code across multiple event source types.

The two changes in this area:

  • EventSource types may now implement interfaces to enable the use of event source types in advanced logging systems that use interfaces to define a common logging target.
  • The concept of a utility event source type (defined as an abstract class deriving from EventSource) is introduced to support sharing code across multiple event source types in a project (e.g. for optimized WriteEvent() overloads).

Please find the details for these changes detailed in the updated EventSource User’s Guide included with the NuGet package.

What Stayed the Same?

Everything that was covered in the original Beta announcement as well as the RC announcement relating to the EventSource core functionality still applies. Here are the highlights:

Using EventSource

Whether you use the EventSource NuGet package or the class that already ships with the .NET Framework, depends on which platforms and features you need:

  1. .NET Framework 4.5 and no need for channel support: we recommend you use the EventSource type that ships in the framework.

  2. .NET Framework 3.5 or 4.0 or need for channel support: we recommend you use the Microsoft.Diagnostics.Tracing.EventSource NuGet package.

Please note that the namespaces between the two choices differ (1) uses the System namespaces while (2) uses the Microsoft namespace.

For build time validation of your event sources (whether deriving from the framework EventSource type or the NuGet type) you may use the Microsoft.Diagnostics.Tracing.EventRegister NuGet package. This is independent of whether you use option (1) or option (2).

Sending Events to the Windows Event Log

Event log support is a new feature provided with this NuGet package. It enables you to specify one additional destination for EventSource events – an application-defined event log. That means that all of your events will show up in a part of the event log that is specific to your app.

In the screenshot below, you will see an area highlighted. That’s the part of the event log that our demo code writes to -- Samples\EventSourceDemos\EventLog – and yours would be similar. Your app events might show up under a node such as: MyCompany\MyApp.

The following code is an example of an ETW event definition that takes advantage of this new feature.

[EventSource(Name = "Samples-EventSourceDemos-EventLog")]
public sealed class MinimalEventSource : EventSource
{
    public static MinimalEventSource Log = new MinimalEventSource();

    [Event(1, Message="{0} -> {1}", Channel = EventChannel.Admin)]
    public void Load(long baseAddress, string imageName)
    {
        WriteEvent(1, baseAddress, imageName);
    }
}

To use this feature, you specify the ETW channel you want to write to in the Channel property of the Event attribute. The Event attribute is associated with the ETW event method your event source defines. In the class above, that’s the Load method.

The NuGet package supports the four predefined ETW channels that the Windows Event Log defines: Admin, Operational, Analytics and Debug (see the ETW channel documentation for more information). You can see how those show up in the screenshot above. We also used an existing ‘Message’ attribute to create a formatted string for our message.

With the above definition (and a registration step detailed later), the Load event will write an event to the Admin event log each time it is called. This log can be found in the Event Viewer tool under the node Applications and Services Logs / Samples / EventSourceDemos / EventLog. Notice that the three-element name specified in the EventSourceAttribute determines the location of the log.

In order for the windows event viewer to know that there is a new source of events to log, it is necessary that you register your EventSource with the operating system, typically when your application is deployed or installed. This operation requires administrator permissions. The artifacts needed for registration (a manifest file and a resource DLL) are generated at build time through a build step injected in your project (when you add the NuGet package reference).

Registering your EventSource

When you install the EventSource NuGet package, the build step previously mentioned generates the following files for each EventSource in your application:

  • <AssemblyName>.<EventSourceTypeName>.etwManifest.man
  • <AssemblyName>.<EventSourceTypeName>.etwManifest.dll.

These files need to be registered with the operating system to enable channel support. To do this you run the following command after the files are in their final deployed location:

wevtutil.exe im <EtwManifestManFile>
             /rf:"<FullPathToEtwManifestDllFile>"
             /mf:"<FullPathToEtwManifestDllFile>"

Once this registration command is executed, all subsequent calls to MinimalEventSource.Log.Load(), from any process on that machine, will automatically result in events in the Windows Event log.

Note: you can provide localized strings for your EventSource by using the LocalizationResources property on the EventSourceAttribute associated with your EventSource type.

EventSource build-time validation for everybody

We’ve received feedback that the build-time validation included in the beta release of EventSource was providing a significant benefit to anybody that was defining their own event source. This feedback was the same for users of the EventSource NuGet package version and the system one (System.Diagnostics.Tracing.EventSource). As a result, we have released this functionality in the EventRegister NuGet package, which can be referenced from any project that uses some variation of EventSource. And, in order to maintain a seamless experience for the users of the NuGet EventSource package, EventSource is a dependent on EventRegister, so you’ll only need to add a reference to the EventSource package, and you’ll get validation/registration pulled in transparently.

We’ve also improved the validation experience. EventRegister will now report all validation failures for each event source type defined in your projects, instead of simply stopping at the first error it encounters. Here’s some sample output you may get in your error tool window:

Sample code

This release includes an update for the EventSource samples NuGet package. The easiest way to use the samples is to create a new console application called DemoEventSource in Visual Studio and then reference the EventSource Samples NuGet package from that project. The source code is part of the package and the Readme.txt file will tell you how to wire up your main program to the sample code.

Summary

Today, we’ve shipped the stable 1.0 packages for Microsoft.Diagnostics.Tracing.EventSource and Microsoft.Diagnostics.Tracing.EventRegister. Please let us know what you think, what works well, and what you would like to see improved.

Leave a Comment
  • Please add 4 and 2 and type the answer here:
  • Post
  • Hi,

    Can we please have a better description of what this is and what the advantages are of using it.

    Thank You

  • Awesome!   My project is currently restricted to using .NET 4.0 and unable to use preview / beta software.   With this release at stable and available, I can start using it in my production.  

    Enabling the channel to log to event source is icing on the cake because it will enable us to more easily log significant events for the quick lookup in event viewer.

    Great work Immo, VanceM, and others on the team!

  • @Anon

    this is a Wrapper to use ETW (Event Tracing for Windows: msdn.microsoft.com/.../bb968803%28v=vs.85%29.aspx) easily with .net.

    It was added in .net 4.5, but not all developers can use .net 4.5, so it is better to have such a NuGet package which can be also updated faster.

  • @Anon: Apologies if our post didn't provide enough context. I believe Andre provided a great TL;DR. Let me know if you'd like to get more information.

    @Dan: Glad you liked it. The kudos go entirely to Cosmin and Vance. I was merely assisting in getting the message out the door -- which also means that the issue @Anon raised is on my plate :-).

    @Andre: Thanks for jumping in!

  • That is great news. The main power of ETW events are the call stacks you get for free. What is the story for .NET 3.5 mixed call stacks? What other ETW Providers are needed to be able to decode the call stacks of my events in WPA? I had many problems with .NET 4.0 already. It seems that managed stack walking only works for .NET >= 4.5.

  • @Alois Kraus: Alois, please try using PerfView (available from the "Download Center") in order to collect your traces. Once they're collected you can use WPA to view the callstacks (WPR has spotty support for managed stacks in 3.5)

  • Why are the DOCX files added to every project? It is annoying to remove them every time again. I don't want those files in my Version control.

  • When I add the nuget packet for EventSource it pulls in the rc-reference to EventRegister, which does not work when I try to compile my solution (can't verify strong name). I have to manually update EventRegister to the current version to get it working.

  • Heya, sort of unrelated, but this seems like the most relevant place to ask -- I noticed ClrMd has been bumped out of prerelease as well. Was that related to this change, or has there also been some significant change to ClrMd? I think ClrMd rules, so would love to hear about any new features or improvements Lee and the runtime team have shipped.

    cheers

  • Hi Kieran.  We are currently working on a handful of features for ClrMD.  The current plan is to add a bit more surface area (there are a few things missing from ClrMD that SOS can do, like inspecting parameters/local variables) that we plan on adding.  After that there's a *small* amount of breaking changes we need to make due to feedback from the community...we will do that in a slow way, starting with adding corrected methods and obsoleting a small amount of broken things, then after that has been out a while we will move on to a 1.0, stable release.

    That's the plan anyway.  We don't have a definite timetable I can share, but in short, we are still supporting it and continuing to release improvements.  Feel free to message me via nuget or at "leculver {at} microsoft {dot} com" if you have any questions.

  • Hi, thanks for the great work and articles you've posted about event source. I am excited to use it but have a question about event ids in the event log.

    Because structured logging was so painful previously and yet we still wanted SCOM to be able to identify certain events without having to parse the event message we came up with a "smart key" for event ids. Where part of the number would represent what happened and another part would represent approximately where it happened (closer to what functional area of the system the event was getting logged from). With event source, I know we can now easily move this over to the event log entry itself (by making these method parameters) and have to use the smart key anymore; however, we need a transition period before our SCOM rules are redefined and so we still need the event ids. So here is my question. Is it possible other than by the Event attribute to be able to set the event id? I really can't write overloads for each of the different event IDs we need for each event (way too many).

    Thanks in advance,

    Carlos

  • When I use the Opcode "Info" I see 0 as "Opcode Name" in xperfview and nothing in WPA.exe instead of win:Info. Is this a bug or "by design"?

  • I can´t see the debug and analityc trece files, can somebody help me to solve this?

  • My EventSource is added with several default keywords: session0, sessions1, ... how can I get rid of these keywords?

Page 1 of 1 (14 items)