diff --git a/src/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md b/src/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md index 85313c6a033e..eebc041a079f 100644 --- a/src/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md +++ b/src/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md @@ -162,12 +162,12 @@ Thus the event names only need to be unique within a component. Short names make `IsEnabled()` faster. * DO - use activities (see [Activity Users Guide](ActivityUserGuide.md)) for events that are -marking the begining and end of a interval of time. The key value of Activities is that they -indicate that they represent a DURATION, and they also track what 'causeed' them (and thus -logging systems can stitch together a 'causality graph'. + marking the begining and end of an interval of time. The key value of Activities is that they + indicate that they represent a DURATION, and they also track what 'caused' them (and thus + logging systems can stitch together a 'causality graph'). -* DO - If for some reason you can't use Activies, and your events mark the start and stop of -an interval of time, use the 'Start' and 'Stop' suffixes on the events. +* DO - If for some reason you can't use Activities, and your events mark the start and stop of + an interval of time, use the 'Start' and 'Stop' suffixes on the events. ### Payloads @@ -176,20 +176,20 @@ an interval of time, use the 'Start' and 'Stop' suffixes on the events. and compatible. * CONSIDER creating an explicit type for the payload. The main value for doing this is that the -receiver can cast the received object to that type and immediately fetch fields (with anonymous types -reflection must be used to fetch fields). This is both easier to program and more efficient. -Thus in scenarios where there is likely high-volume filtering to be done by the logging listener, having -this type available to do the cast is valuable. Note that this type needs to be made public (since -the listener needs to see it), and should be under the namespace System.Diagnostics.DiagnosticSource.PayloadTypes. -Note that if there is doubt about the value DO NOT create an explicit type, as you CAN convert from -an anonymous type to a explicit type compatibly in the future, but once you expose the payload type -you must keep it forever. The payload type should simply have C# 'TYPE NAME {get; set; }' properties -(you can't use fields). You may add new properties as needed in the future. + receiver can cast the received object to that type and immediately fetch fields (with anonymous types + reflection must be used to fetch fields). This is both easier to program and more efficient. + Thus in scenarios where there is likely high-volume filtering to be done by the logging listener, having + this type available to do the cast is valuable. Note that this type needs to be made public (since + the listener needs to see it), and should be under the namespace System.Diagnostics.DiagnosticSource.PayloadTypes. + Note that if there is doubt about the value DO NOT create an explicit type, as you CAN convert from + an anonymous type to a explicit type compatibly in the future, but once you expose the payload type + you must keep it forever. The payload type should simply have C# 'TYPE NAME {get; set; }' properties + (you can't use fields). You may add new properties as needed in the future. * CONSIDER in high volume cases (e.g. > 1K/sec) consider reusing the payload object instead of -creating a new one each time the event is fired. This only works well if you already have locking -or exclusive objects where you can remember the payload for the 'next' event to send easily and -correctly (you are only saving an object allocation, which is not large). + creating a new one each time the event is fired. This only works well if you already have locking + or exclusive objects where you can remember the payload for the 'next' event to send easily and + correctly (you are only saving an object allocation, which is not large). * CONSIDER - if you have an event that is so frequent that the performance of the logging is an important consideration, **and** you have only one data item **and** it is unlikely that