What is the purpose of last argument of type `IDictionary<String, String>` in the `EventListener.EnableEvents` method?

Question

I am trying to figure out how the last argument (IDictionary<String, String>) in the method EventListener.EnableEvents(EventSource, EventLevel, EventKeywords, IDictionary<String, String>) affects the behavior of the method.

I have checked the MSDN documentation but the description is not clear and there is no example how to use it. What are the event's arguments and how are they specified in the dictionary? If some one can give an example, it would be more than perfect.

Answer 1

The closest I found to an answer to this was this article on MSDN.

You are logging events from an application and you also want to capture events from event sources that are not defined within the application, but are relevant to the application. For example, you want to capture the RequestStarted event raised by ASP.NET when a request is received by your application. However, you do not want to collect all of these events because the volume generated by these additional sources would overwhelm your logging store or would make it very difficult to analyse the logging information. To resolve this you need to collect only a sample of the events, rather than all of them, and also be able to filter the processes from which you collect events.

Answer 2

The IDictionary<String, String> in EventListener.EnableEvents are command arguments and are passed to the EventSource. Basically it's an extensibility mechanism built into EventSource. For example, a custom event source could override OnEventCommand and respond to arbitrary commands.

The command arguments currently supported by the System.Diagnostics.Tracing.EventSource are "ActivitySamplingStartEvent", "ActivitySampling", and "EtwSessionKeyword".

Here's an example on how they are used from Semantic Logging Application Block Sampling and filtering events article:

var listener = new ObservableEventListener();

listener.EnableEvents("MyCustomEventSource", 
         EventLevel.Informational, Keywords.None,
         new Dictionary<string, string> {
           { "ActivitySampling", "true" }
         });