4 <name>System.Diagnostics.DiagnosticSource</name>
7 <member name="T:System.Diagnostics.DiagnosticSource">
9 This is the basic API to 'hook' parts of the framework. It is like an EventSource
10 (which can also write object), but is intended to log complex objects that can't be serialized.
12 Please See the DiagnosticSource Users Guide
13 https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md
14 for instructions on its use.
17 <member name="M:System.Diagnostics.DiagnosticSource.Write(System.String,System.Object)">
19 Write is a generic way of logging complex payloads. Each notification
20 is given a name, which identifies it as well as a object (typically an anonymous type)
21 that gives the information to pass to the notification, which is arbitrary.
23 The name should be short (so don't use fully qualified names unless you have to
24 to avoid ambiguity), but you want the name to be globally unique. Typically your componentName.eventName
25 where componentName and eventName are strings less than 10 characters are a good compromise.
26 notification names should NOT have '.' in them because component names have dots and for them both
27 to have dots would lead to ambiguity. The suggestion is to use _ instead. It is assumed
28 that listeners will use string prefixing to filter groups, thus having hierarchy in component
31 <param name="name">The name of the event being written.</param>
32 <param name="value">An object that represent the value being passed as a payload for the event.
33 This is often a anonymous type which contains several sub-values.</param>
35 <member name="M:System.Diagnostics.DiagnosticSource.IsEnabled(System.String)">
37 Optional: if there is expensive setup for the notification, you can call IsEnabled
38 before doing this setup. Consumers should not be assuming that they only get notifications
39 for which IsEnabled is true however, it is optional for producers to call this API.
40 The name should be the same as what is passed to Write.
42 <param name="name">The name of the event being written.</param>
44 <member name="T:System.Diagnostics.DiagnosticListener">
46 A DiagnosticListener is something that forwards on events written with DiagnosticSource.
47 It is an IObservable (has Subscribe method), and it also has a Subscribe overload that
48 lets you specify a 'IsEnabled' predicate that users of DiagnosticSource will use for
51 The item in the stream is a KeyValuePair[string, object] where the string is the name
52 of the diagnostic item and the object is the payload (typically an anonymous type).
54 There may be many DiagnosticListeners in the system, but we encourage the use of
55 The DiagnosticSource.DefaultSource which goes to the DiagnosticListener.DefaultListener.
57 If you need to see 'everything' you can subscribe to the 'AllListeners' event that
58 will fire for every live DiagnosticListener in the appdomain (past or present).
60 Please See the DiagnosticSource Users Guide
61 https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md
62 for instructions on its use.
65 <member name="P:System.Diagnostics.DiagnosticListener.AllListeners">
67 When you subscribe to this you get callbacks for all NotificationListeners in the appdomain
68 as well as those that occurred in the past, and all future Listeners created in the future.
71 <member name="M:System.Diagnostics.DiagnosticListener.Subscribe(System.IObserver{System.Collections.Generic.KeyValuePair{System.String,System.Object}},System.Predicate{System.String})">
73 Add a subscriber (Observer). If 'IsEnabled' == null (or not present), then the Source's IsEnabled
74 will always return true.
77 <member name="M:System.Diagnostics.DiagnosticListener.Subscribe(System.IObserver{System.Collections.Generic.KeyValuePair{System.String,System.Object}})">
79 Same as other Subscribe overload where the predicate is assumed to always return true.
82 <member name="M:System.Diagnostics.DiagnosticListener.#ctor(System.String)">
84 Make a new DiagnosticListener, it is a NotificationSource, which means the returned result can be used to
85 log notifications, but it also has a Subscribe method so notifications can be forwarded
86 arbitrarily. Thus its job is to forward things from the producer to all the listeners
87 (multi-casting). Generally you should not be making your own DiagnosticListener but use the
88 DiagnosticListener.Default, so that notifications are as 'public' as possible.
91 <member name="M:System.Diagnostics.DiagnosticListener.Dispose">
93 Clean up the NotificationListeners. Notification listeners do NOT DIE ON THEIR OWN
94 because they are in a global list (for discoverability). You must dispose them explicitly.
95 Note that we do not do the Dispose(bool) pattern because we frankly don't want to support
96 subclasses that have non-managed state.
99 <member name="P:System.Diagnostics.DiagnosticListener.Name">
101 When a DiagnosticListener is created it is given a name. Return this.
104 <member name="M:System.Diagnostics.DiagnosticListener.ToString">
106 Return the name for the ToString() to aid in debugging.
110 <member name="M:System.Diagnostics.DiagnosticListener.IsEnabled(System.String)">
112 Override abstract method
115 <member name="M:System.Diagnostics.DiagnosticListener.Write(System.String,System.Object)">
117 Override abstract method
120 <member name="T:System.Diagnostics.DiagnosticListener.AllListenerObservable">
122 Logically AllListenerObservable has a very simple task. It has a linked list of subscribers that want
123 a callback when a new listener gets created. When a new DiagnosticListener gets created it should call
124 OnNewDiagnosticListener so that AllListenerObservable can forward it on to all the subscribers.
127 <member name="M:System.Diagnostics.DiagnosticListener.AllListenerObservable.OnNewDiagnosticListener(System.Diagnostics.DiagnosticListener)">
129 Called when a new DiagnosticListener gets created to tell anyone who subscribed that this happened.
131 <param name="diagnosticListener"></param>
133 <member name="M:System.Diagnostics.DiagnosticListener.AllListenerObservable.Remove(System.Diagnostics.DiagnosticListener.AllListenerObservable.AllListenerSubscription)">
135 Remove 'subscription from the list of subscriptions that the observable has. Called when
136 subscriptions are disposed. Returns true if the subscription was removed.
139 <member name="T:System.Diagnostics.DiagnosticListener.AllListenerObservable.AllListenerSubscription">
141 One node in the linked list of subscriptions that AllListenerObservable keeps. It is
142 IDisposable, and when that is called it removes itself from the list.
145 <member name="T:System.Diagnostics.DiagnosticSourceEventSource">
147 DiagnosticSourceEventSource serves two purposes
149 1) It allows debuggers to inject code via Function evaluation. This is the purpose of the
150 BreakPointWithDebuggerFuncEval function in the 'OnEventCommand' method. Basically even in
151 release code, debuggers can place a breakpoint in this method and then trigger the
152 DiagnosticSourceEventSource via ETW. Thus from outside the process you can get a hook that
153 is guaranteed to happen BEFORE any DiangosticSource events (if the process is just starting)
154 or as soon as possible afterward if it is on attach.
156 2) It provides a 'bridge' that allows DiagnosticSource messages to be forwarded to EventListers
157 or ETW. You can do this by enabling the Microsoft-Diagnostics-DiagnosticSource with the
158 'Events' keyword (for diagnostics purposes, you should also turn on the 'Messages' keyword.
160 This EventSource defines a EventSource argument called 'FilterAndPayloadSpecs' that defines
161 what DiagnsoticSources to enable and what parts of the payload to serialize into the key-value
162 list that will be forwarded to the EventSource. If it is empty, all serializable parts of
163 every DiagnosticSource event will be forwarded (this is NOT recommended for monitoring but
164 can be useful for discovery).
166 The FilterAndPayloadSpecs is one long string with the following structures
168 * It is a newline separated list of FILTER_AND_PAYLOAD_SPEC
169 * a FILTER_AND_PAYLOAD_SPEC can be
170 * EVENT_NAME : TRANSFORM_SPECS
171 * EMPTY - turns on all sources with implicit payload elements.
172 * an EVENTNAME can be
173 * DIAGNOSTIC_SOURCE_NAME / DIAGNOSTC_EVENT_NAME @ EVENT_SOURCE_EVENTNAME - give the name as well as the EventSource event to log it under.
174 * DIAGNOSTIC_SOURCE_NAME / DIAGNOSTC_EVENT_NAME
175 * DIAGNOSTIC_SOURCE_NAME - which wildcards every event in the Diagnostic source or
176 * EMPTY - which turns on all sources
177 * TRANSFORM_SPEC is a semicolon separated list of TRANSFORM_SPEC, which can be
178 * - TRANSFORM_SPEC - the '-' indicates that implicit payload elements should be suppressed
179 * VARIABLE_NAME = PROPERTY_SPEC - indicates that a payload element 'VARIABLE_NAME' is created from PROPERTY_SPEC
180 * PROPERTY_SPEC - This is a shortcut where VARIABLE_NAME is the LAST property name
181 * a PROPERTY_SPEC is basically a list of names separated by '.'
182 * PROPERTY_NAME - fetches a property from the DiagnosticSource payload object
183 * PROPERTY_NAME . PROPERTY NAME - fetches a sub-property of the object.
187 "BridgeTestSource1/TestEvent1:cls_Point_X=cls.Point.X;cls_Point_Y=cls.Point.Y\r\n" +
188 "BridgeTestSource2/TestEvent2:-cls.Url"
190 This indicates that two events should be turned on, The 'TestEvent1' event in BridgeTestSource1 and the
191 'TestEvent2' in BridgeTestSource2. In the first case, because the transform did not begin with a -
192 any primitive type/string of 'TestEvent1's payload will be serialized into the output. In addition if
193 there a property of the payload object called 'cls' which in turn has a property 'Point' which in turn
194 has a property 'X' then that data is also put in the output with the name cls_Point_X. Similarly
195 if cls.Point.Y exists, then that value will also be put in the output with the name cls_Point_Y.
197 For the 'BridgeTestSource2/TestEvent2' event, because the - was specified NO implicit fields will be
198 generated, but if there is a property call 'cls' which has a property 'Url' then that will be placed in
199 the output with the name 'Url' (since that was the last property name used and no Variable= clause was
204 "BridgeTestSource1\r\n" +
207 This will enable all events for the BridgeTestSource1 and BridgeTestSource2 sources. Any string/primitive
208 properties of any of the events will be serialized into the output.
214 This turns on all DiagnosticSources Any string/primitive properties of any of the events will be serialized
215 into the output. This is not likely to be a good idea as it will be very verbose, but is useful to quickly
216 discover what is available.
219 * How data is logged in the EventSource
221 By default all data from Diagnostic sources is logged to the the DiagnosticEventSouce event called 'Event'
222 which has three fields
226 IEnumerable[KeyValuePair[string, string]] Argument
228 However to support start-stop activity tracking, there are six other events that can be used
234 RecursiveActivity1Start
235 RecursiveActivity1Stop
237 By using the SourceName/EventName@EventSourceName syntax, you can force particular DiagnosticSource events to
238 be logged with one of these EventSource events. This is useful because the events above have start-stop semantics
239 which means that they create activity IDs that are attached to all logging messages between the start and
240 the stop (see https://blogs.msdn.microsoft.com/vancem/2015/09/14/exploring-eventsource-activity-correlation-and-causation-features/)
242 For example the specification
244 "MyDiagnosticSource/RequestStart@Activity1Start\r\n" +
245 "MyDiagnosticSource/RequestStop@Activity1Stop\r\n" +
246 "MyDiagnosticSource/SecurityStart@Activity2Start\r\n" +
247 "MyDiagnosticSource/SecurityStop@Activity2Stop\r\n"
249 Defines that RequestStart will be logged with the EventSource Event Activity1Start (and the cooresponding stop) which
250 means that all events caused between these two markers will have an activity ID assocatied with this start event.
251 Simmilarly SecurityStart is mapped to Activity2Start.
253 Note you can map many DiangosticSource events to the same EventSource Event (e.g. Activity1Start). As long as the
254 activities don't nest, you can reuse the same event name (since the payloads have the DiagnosticSource name which can
255 disambiguate). However if they nest you need to use another EventSource event because the rules of EventSource
256 activities state that a start of the same event terminates any existing activity of the same name.
258 As its name suggests RecursiveActivity1Start, is marked as recursive and thus can be used when the activity can nest with
259 itself. This should not be a 'top most' activity because it is not 'self healing' (if you miss a stop, then the
260 activity NEVER ends).
262 See the DiagnosticSourceEventSourceBridgeTest.cs for more explicit examples of using this bridge.
265 <member name="F:System.Diagnostics.DiagnosticSourceEventSource.Keywords.Messages">
267 Indicates diagnostics messages from DiagnosticSourceEventSource should be included.
270 <member name="F:System.Diagnostics.DiagnosticSourceEventSource.Keywords.Events">
272 Indicates that all events from all diagnostic sources should be forwarded to the EventSource using the 'Event' event.
275 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.Message(System.String)">
277 Used to send ad-hoc diagnostics to humans.
280 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.Event(System.String,System.String,System.Collections.Generic.IEnumerable{System.Collections.Generic.KeyValuePair{System.String,System.String}})">
282 Events from DiagnosticSource can be forwarded to EventSource using this event.
285 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.EventJson(System.String,System.String,System.String)">
287 This is only used on V4.5 systems that don't have the ability to log KeyValuePairs directly.
288 It will eventually go away, but we should always reserve the ID for this.
291 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.Activity1Start(System.String,System.String,System.Collections.Generic.IEnumerable{System.Collections.Generic.KeyValuePair{System.String,System.String}})">
293 Used to mark the beginning of an activity
296 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.Activity1Stop(System.String,System.String,System.Collections.Generic.IEnumerable{System.Collections.Generic.KeyValuePair{System.String,System.String}})">
298 Used to mark the end of an activity
301 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.Activity2Start(System.String,System.String,System.Collections.Generic.IEnumerable{System.Collections.Generic.KeyValuePair{System.String,System.String}})">
303 Used to mark the beginning of an activity
306 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.Activity2Stop(System.String,System.String,System.Collections.Generic.IEnumerable{System.Collections.Generic.KeyValuePair{System.String,System.String}})">
308 Used to mark the end of an activity that can be recursive.
311 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.RecursiveActivity1Start(System.String,System.String,System.Collections.Generic.IEnumerable{System.Collections.Generic.KeyValuePair{System.String,System.String}})">
313 Used to mark the beginning of an activity
316 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.RecursiveActivity1Stop(System.String,System.String,System.Collections.Generic.IEnumerable{System.Collections.Generic.KeyValuePair{System.String,System.String}})">
318 Used to mark the end of an activity that can be recursive.
321 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.NewDiagnosticListener(System.String)">
323 Fires when a new DiagnosticSource becomes available.
325 <param name="SourceName"></param>
327 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.#ctor">
329 This constructor uses EventSourceSettings which is only available on V4.6 and above
330 systems. We use the EventSourceSettings to turn on support for complex types.
333 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.OnEventCommand(System.Diagnostics.Tracing.EventCommandEventArgs)">
335 Called when the EventSource gets a command from a EventListener or ETW.
338 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.BreakPointWithDebuggerFuncEval">
340 A function which is fully interruptible even in release code so we can stop here and
341 do function evaluation in the debugger. Thus this is just a place that is useful
342 for the debugger to place a breakpoint where it can inject code with function evaluation
345 <member name="T:System.Diagnostics.DiagnosticSourceEventSource.FilterAndTransform">
347 FilterAndTransform represents on transformation specification from a DiagnosticsSource
348 to EventSource's 'Event' method. (e.g. MySource/MyEvent:out=prop1.prop2.prop3).
349 Its main method is 'Morph' which takes a DiagnosticSource object and morphs it into
350 a list of string,string key value pairs.
352 This method also contains that static 'Create/Destroy FilterAndTransformList, which
353 simply parse a series of transformation specifications.
356 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.FilterAndTransform.CreateFilterAndTransformList(System.Diagnostics.DiagnosticSourceEventSource.FilterAndTransform@,System.String,System.Diagnostics.DiagnosticSourceEventSource)">
358 Parses filterAndPayloadSpecs which is a list of lines each of which has the from
360 DiagnosticSourceName/EventName:PAYLOAD_SPEC
362 where PAYLOADSPEC is a semicolon separated list of specifications of the form
364 OutputName=Prop1.Prop2.PropN
366 Into linked list of FilterAndTransform that together forward events from the given
367 DiagnosticSource's to 'eventSource'. Sets the 'specList' variable to this value
368 (destroying anything that was there previously).
370 By default any serializable properties of the payload object are also included
371 in the output payload, however this feature and be tuned off by prefixing the
372 PAYLOADSPEC with a '-'.
375 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.FilterAndTransform.DestroyFilterAndTransformList(System.Diagnostics.DiagnosticSourceEventSource.FilterAndTransform@)">
377 This destroys (turns off) the FilterAndTransform stopping the forwarding started with CreateFilterAndTransformList
379 <param name="specList"></param>
381 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.FilterAndTransform.#ctor(System.String,System.Int32,System.Int32,System.Diagnostics.DiagnosticSourceEventSource,System.Diagnostics.DiagnosticSourceEventSource.FilterAndTransform)">
383 Creates one FilterAndTransform specification from filterAndPayloadSpec starting at 'startIdx' and ending just before 'endIdx'.
384 This FilterAndTransform will subscribe to DiagnosticSources specified by the specification and forward them to 'eventSource.
385 For convenience, the 'Next' field is set to the 'next' parameter, so you can easily form linked lists.
388 <member name="T:System.Diagnostics.DiagnosticSourceEventSource.TransformSpec">
390 Transform spec represents a string that describes how to extract a piece of data from
391 the DiagnosticSource payload. An example string is OUTSTR=EVENT_VALUE.PROP1.PROP2.PROP3
392 It has a Next field so they can be chained together in a linked list.
395 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.TransformSpec.#ctor(System.String,System.Int32,System.Int32,System.Diagnostics.DiagnosticSourceEventSource.TransformSpec)">
397 parse the strings 'spec' from startIdx to endIdx (points just beyond the last considered char)
398 The syntax is ID1=ID2.ID3.ID4 .... Where ID1= is optional.
401 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.TransformSpec.Morph(System.Object)">
403 Given the DiagnosticSourcePayload 'obj', compute a key-value pair from it. For example
404 if the spec is OUTSTR=EVENT_VALUE.PROP1.PROP2.PROP3 and the ultimate value of PROP3 is
405 10 then the return key value pair is KeyValuePair("OUTSTR","10")
408 <member name="F:System.Diagnostics.DiagnosticSourceEventSource.TransformSpec.Next">
410 A public field that can be used to form a linked list.
413 <member name="T:System.Diagnostics.DiagnosticSourceEventSource.TransformSpec.PropertySpec">
415 A PropertySpec represents information needed to fetch a property from
416 and efficiently. Thus it represents a '.PROP' in a TransformSpec
417 (and a transformSpec has a list of these).
420 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.TransformSpec.PropertySpec.#ctor(System.String,System.Diagnostics.DiagnosticSourceEventSource.TransformSpec.PropertySpec)">
422 Make a new PropertySpec for a property named 'propertyName'.
423 For convenience you can set he 'next' field to form a linked
424 list of PropertySpecs.
427 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.TransformSpec.PropertySpec.Fetch(System.Object)">
429 Given an object fetch the property that this PropertySpec represents.
432 <member name="F:System.Diagnostics.DiagnosticSourceEventSource.TransformSpec.PropertySpec.Next">
434 A public field that can be used to form a linked list.
437 <member name="T:System.Diagnostics.DiagnosticSourceEventSource.TransformSpec.PropertySpec.PropertyFetch">
439 PropertyFetch is a helper class. It takes a PropertyInfo and then knows how
440 to efficiently fetch that property from a .NET object (See Fetch method).
441 It hides some slightly complex generic code.
444 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.TransformSpec.PropertySpec.PropertyFetch.FetcherForProperty(System.Reflection.PropertyInfo)">
446 Create a property fetcher from a .NET Reflection PropertyInfo class that
447 represents a property of a particular type.
450 <member name="M:System.Diagnostics.DiagnosticSourceEventSource.TransformSpec.PropertySpec.PropertyFetch.Fetch(System.Object)">
452 Given an object, fetch the property that this propertyFech represents.
455 <member name="T:System.Diagnostics.DiagnosticSourceEventSource.CallbackObserver`1">
457 CallbackObserver is a adapter class that creates an observer (which you can pass
458 to IObservable.Subscribe), and calls the given callback every time the 'next'
459 operation on the IObserver happens.
461 <typeparam name="T"></typeparam>