From 1663f0af1b88f0dd342d13b555bc366eb65f1c05 Mon Sep 17 00:00:00 2001 From: Sung Yoon Whang Date: Thu, 1 Aug 2019 01:13:09 -0700 Subject: [PATCH 01/12] System.Diagnostics.Tracing.* --- .../DiagnosticCounter.xml | 18 +++++++++++++----- .../EventCounter.xml | 15 +++++++++++---- .../IncrementingEventCounter.xml | 17 ++++++++++++----- .../IncrementingPollingCounter.xml | 19 ++++++++++++++----- .../PollingCounter.xml | 7 +++++-- 5 files changed, 55 insertions(+), 21 deletions(-) diff --git a/xml/System.Diagnostics.Tracing/DiagnosticCounter.xml b/xml/System.Diagnostics.Tracing/DiagnosticCounter.xml index 5e38b479998..407d64a6a97 100644 --- a/xml/System.Diagnostics.Tracing/DiagnosticCounter.xml +++ b/xml/System.Diagnostics.Tracing/DiagnosticCounter.xml @@ -65,9 +65,17 @@ System.String - To be added. + The display name of the counter. To be added. - To be added. + + + + @@ -137,9 +145,9 @@ After being disposed, this counter will do nothing, and its resources will be re System.Diagnostics.Tracing.EventSource - To be added. + The EventSource that this counter is attached to. To be added. - To be added. + @@ -158,7 +166,7 @@ After being disposed, this counter will do nothing, and its resources will be re System.String - To be added. + The name of this counter. To be added. To be added. diff --git a/xml/System.Diagnostics.Tracing/EventCounter.xml b/xml/System.Diagnostics.Tracing/EventCounter.xml index 0fbc9ec7bff..67811481804 100644 --- a/xml/System.Diagnostics.Tracing/EventCounter.xml +++ b/xml/System.Diagnostics.Tracing/EventCounter.xml @@ -35,7 +35,7 @@ Provides the ability to collect statistics for very frequent events through the class. class, see the [Introduction Tutorial: How to measure performance for very frequent events using EventCounters](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md) topic. @@ -158,9 +158,16 @@ For an example of how to use the - To be added. - To be added. - To be added. + The value to be written. + Writes the metric if performance counters are on. + + method, see the [Introduction Tutorial: How to measure performance for very frequent events using EventCounters](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md) topic. + + ]]> + diff --git a/xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml b/xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml index 9d9e13a6645..10fe34c3f68 100644 --- a/xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml +++ b/xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml @@ -18,7 +18,9 @@ @@ -46,7 +48,7 @@ that they are attached to unless they are explicitly disposed. + live as long as the that they are attached to unless they are explicitly disposed. ]]> @@ -68,9 +70,14 @@ Incrementing event counters live as long as the + diff --git a/xml/System.Diagnostics.Tracing/IncrementingPollingCounter.xml b/xml/System.Diagnostics.Tracing/IncrementingPollingCounter.xml index 9785b6525c7..b0bd59e224b 100644 --- a/xml/System.Diagnostics.Tracing/IncrementingPollingCounter.xml +++ b/xml/System.Diagnostics.Tracing/IncrementingPollingCounter.xml @@ -42,14 +42,18 @@ The name for this instance. - The event source. - To be added. + The object this instance is a part of. + A method that will be used to poll the value. Initializes a new instance of the class. objects live as long as the that they are attached to unless they are explicitly disposed. +The method passed as a parameter is used for polling the values at the interval specified by the listener. This method is expected to return an incrementing float value; otherwise, an increment of a negative value may be reported. + +For an example usage of inside the runtime as one of the runtime performance counters, please refer to the CoreCLR source for runtime performance counter EventSource - [System.Runtime](https://github.com/dotnet/coreclr/blob/master/src/System.Private.CoreLib/src/System/Diagnostics/Eventing/RuntimeEventSource.cs). + ]]> @@ -70,9 +74,14 @@ System.TimeSpan - To be added. - To be added. - To be added. + The rate at which this metric should be displayed as. + + + diff --git a/xml/System.Diagnostics.Tracing/PollingCounter.xml b/xml/System.Diagnostics.Tracing/PollingCounter.xml index e4ee8149d97..0a75ccf96e0 100644 --- a/xml/System.Diagnostics.Tracing/PollingCounter.xml +++ b/xml/System.Diagnostics.Tracing/PollingCounter.xml @@ -43,12 +43,15 @@ The name for this instance. The event source. - To be added. + A method that will be used to poll the value. Initializes a new instance of the class. is a variant of where instead of the writer having to explicitly call `WriteMetric()` each time a value wants to be tracked, it takes in a callback method to poll for values. It polls and reports a value retrieved from calling `metricProvider` exactly once per the interval requested by the listener. -Polling counters live as long as the that they are attached to unless they are explicitly disposed. + lives as long as the that it is attached to unless they are explicitly disposed. + +For an example usage of inside the runtime as one of the runtime performance counters, please refer to the CoreCLR source for runtime performance counter EventSource - [System.Runtime](https://github.com/dotnet/coreclr/blob/master/src/System.Private.CoreLib/src/System/Diagnostics/Eventing/RuntimeEventSource.cs). ]]> From 2aaa659a8bb825c1e877fac0a52b70668b5dc727 Mon Sep 17 00:00:00 2001 From: Sung Yoon Whang Date: Thu, 1 Aug 2019 02:23:35 -0700 Subject: [PATCH 02/12] System.Diagnotics.Activity* --- xml/System.Diagnostics/Activity.xml | 18 ++++++--- xml/System.Diagnostics/ActivitySpanId.xml | 36 +++++++++-------- xml/System.Diagnostics/ActivityTraceFlags.xml | 4 +- xml/System.Diagnostics/ActivityTraceId.xml | 40 ++++++++++--------- 4 files changed, 56 insertions(+), 42 deletions(-) diff --git a/xml/System.Diagnostics/Activity.xml b/xml/System.Diagnostics/Activity.xml index a44743939e2..aae2b5894f8 100644 --- a/xml/System.Diagnostics/Activity.xml +++ b/xml/System.Diagnostics/Activity.xml @@ -667,12 +667,20 @@ This property should only be used in 'boundary' scenarios where an - To be added. - To be added. + The parent activity's . + The parent activity's . To be added. - To be added. - To be added. - To be added. + Set the parent ID using the W3C convention using a TraceId and a SpanId. + + for convenient chaining. + + + + diff --git a/xml/System.Diagnostics/ActivitySpanId.xml b/xml/System.Diagnostics/ActivitySpanId.xml index 24dd4f28da8..088966097ca 100644 --- a/xml/System.Diagnostics/ActivitySpanId.xml +++ b/xml/System.Diagnostics/ActivitySpanId.xml @@ -189,9 +189,9 @@ The characters in are not all lower-case hexadecimal - To be added. - To be added. - To be added. + The to compare to. + Determines whether two objects have the same value. + if has the same hex value as . To be added. @@ -214,9 +214,9 @@ The characters in are not all lower-case hexadecimal - To be added. - To be added. - To be added. + The to compare to. + Determines whether two objects have the same value. + if is an instance of and has the same hex value as ; otherwise, . To be added. @@ -237,8 +237,8 @@ The characters in are not all lower-case hexadecimal - To be added. - To be added. + Returns the hash of the SpanId. + The hash of the SpanId. To be added. @@ -262,10 +262,12 @@ The characters in are not all lower-case hexadecimal - To be added. - To be added. - To be added. - To be added. + The first to compare. + The second to compare. + Determines whether two specified ActivitySpanIds have the same value. + + if the SpanId of is the same as the SpanId of ; otherwise, . + To be added. @@ -289,10 +291,12 @@ The characters in are not all lower-case hexadecimal - To be added. - To be added. - To be added. - To be added. + The first to compare. + The second to compare. + Compare with another instance of . + + if the SpanId of is different from the SpanId of ; otherwise, . + To be added. diff --git a/xml/System.Diagnostics/ActivityTraceFlags.xml b/xml/System.Diagnostics/ActivityTraceFlags.xml index 2bba38c2f4e..1e4603a2652 100644 --- a/xml/System.Diagnostics/ActivityTraceFlags.xml +++ b/xml/System.Diagnostics/ActivityTraceFlags.xml @@ -45,7 +45,7 @@ An `ActivityTraceFflags` value is returned by the 0 - To be added. + The activity has not been marked with anything. @@ -65,7 +65,7 @@ An `ActivityTraceFflags` value is returned by the 1 - To be added. + Indicates that the Activity (or more likley its parents) has been marked as useful to record. diff --git a/xml/System.Diagnostics/ActivityTraceId.xml b/xml/System.Diagnostics/ActivityTraceId.xml index 9eaa9177edf..53a14a291f1 100644 --- a/xml/System.Diagnostics/ActivityTraceId.xml +++ b/xml/System.Diagnostics/ActivityTraceId.xml @@ -189,9 +189,9 @@ The characters in are not all lower-case hexadecimal - To be added. - To be added. - To be added. + The to compare to. + Compare with another instance of . + if has the same hex value as . To be added. @@ -214,9 +214,9 @@ The characters in are not all lower-case hexadecimal - To be added. - To be added. - To be added. + The to compare to. + Determines whether two objects have the same value. + if is an instance of and has the same hex value as ; otherwise, . To be added. @@ -237,8 +237,8 @@ The characters in are not all lower-case hexadecimal - To be added. - To be added. + Returns the hash of the TraceId. + The hash of the TraceId. To be added. @@ -262,11 +262,12 @@ The characters in are not all lower-case hexadecimal - To be added. - To be added. - To be added. - To be added. - To be added. + The first to compare. + The second to compare. + Determines whether two specified ActivityTraceIds have the same value. + + if the TraceId of is the same as the TraceId of ; otherwise, . + @@ -289,11 +290,12 @@ The characters in are not all lower-case hexadecimal - To be added. - To be added. - To be added. - To be added. - To be added. + The first to compare. + The second to compare. + Determines whether two specified ActivityTraceIds have the same value. + + if the TraceId of is the different from the TraceId of ; otherwise, . + @@ -335,7 +337,7 @@ The characters in are not all lower-case hexadecimal - Returns a 32-aracter hexadecimal string that represents this trace ID. + Returns a 32-character hexadecimal string that represents this trace ID. The 32-character hecxadecimal string representation of this trace ID. To be added. From 309e781565b0d19d63f61c452c85df0ff8b85980 Mon Sep 17 00:00:00 2001 From: Sung Yoon Whang Date: Thu, 1 Aug 2019 03:05:57 -0700 Subject: [PATCH 03/12] DiagnosticSource --- xml/System.Diagnostics/DiagnosticListener.xml | 12 ++++++------ xml/System.Diagnostics/DiagnosticSource.xml | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/xml/System.Diagnostics/DiagnosticListener.xml b/xml/System.Diagnostics/DiagnosticListener.xml index 0762047073d..1e5b314e4f0 100644 --- a/xml/System.Diagnostics/DiagnosticListener.xml +++ b/xml/System.Diagnostics/DiagnosticListener.xml @@ -269,9 +269,9 @@ If setup for the notification is expensive, you can call `IsEnabled` before perf - To be added. - To be added. - To be added. + The activity affected by an external event. + An object that represents the outgoing request. + Invokes the OnActivityExport method of all the subscribers. To be added. @@ -294,9 +294,9 @@ If setup for the notification is expensive, you can call `IsEnabled` before perf - To be added. - To be added. - To be added. + The activity affected by an external event. + An object that represents the incoming request. + Invokes the OnActivityImport method of all the subscribers. To be added. diff --git a/xml/System.Diagnostics/DiagnosticSource.xml b/xml/System.Diagnostics/DiagnosticSource.xml index e52f0a3bd02..5871336311d 100644 --- a/xml/System.Diagnostics/DiagnosticSource.xml +++ b/xml/System.Diagnostics/DiagnosticSource.xml @@ -139,8 +139,8 @@ If there is expensive setup for the notification, you can call this method and p - To be added. - To be added. + The activity affected by an external event. + An object that represents the outgoing request. Transfers state from an activity to some event or operation, such as an outgoing HTTP request, that will occur outside the process. Date: Thu, 1 Aug 2019 08:39:38 -0700 Subject: [PATCH 04/12] Update Activity.xml --- xml/System.Diagnostics/Activity.xml | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/xml/System.Diagnostics/Activity.xml b/xml/System.Diagnostics/Activity.xml index aae2b5894f8..ac7585e99db 100644 --- a/xml/System.Diagnostics/Activity.xml +++ b/xml/System.Diagnostics/Activity.xml @@ -671,9 +671,7 @@ This property should only be used in 'boundary' scenarios where an The parent activity's . To be added. Set the parent ID using the W3C convention using a TraceId and a SpanId. - - for convenient chaining. - + for convenient chaining. - \ No newline at end of file + From 7452a4fa8ecb46ad66c227762fc8bb760f799c4b Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Thu, 1 Aug 2019 08:40:33 -0700 Subject: [PATCH 05/12] Update ActivitySpanId.xml --- xml/System.Diagnostics/ActivitySpanId.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/xml/System.Diagnostics/ActivitySpanId.xml b/xml/System.Diagnostics/ActivitySpanId.xml index 088966097ca..0679af60c9c 100644 --- a/xml/System.Diagnostics/ActivitySpanId.xml +++ b/xml/System.Diagnostics/ActivitySpanId.xml @@ -293,7 +293,7 @@ The characters in are not all lower-case hexadecimal The first to compare. The second to compare. - Compare with another instance of . + Compare with another instance of . if the SpanId of is different from the SpanId of ; otherwise, . @@ -345,4 +345,4 @@ The characters in are not all lower-case hexadecimal - \ No newline at end of file + From 77532d474ab0f3d0e951a944df6dc5ba5978f1d0 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Thu, 1 Aug 2019 08:41:25 -0700 Subject: [PATCH 06/12] Update ActivityTraceId.xml --- xml/System.Diagnostics/ActivityTraceId.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/xml/System.Diagnostics/ActivityTraceId.xml b/xml/System.Diagnostics/ActivityTraceId.xml index 53a14a291f1..89f1f6b67f2 100644 --- a/xml/System.Diagnostics/ActivityTraceId.xml +++ b/xml/System.Diagnostics/ActivityTraceId.xml @@ -190,7 +190,7 @@ The characters in are not all lower-case hexadecimal The to compare to. - Compare with another instance of . + Compare with another instance of . if has the same hex value as . To be added. @@ -343,4 +343,4 @@ The characters in are not all lower-case hexadecimal - \ No newline at end of file + From 293577c85f6eebde3ee423942b8188b02ebdee64 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Fri, 2 Aug 2019 10:23:17 -0700 Subject: [PATCH 07/12] Changed crefs to xrefs --- xml/System.Diagnostics.Tracing/PollingCounter.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/xml/System.Diagnostics.Tracing/PollingCounter.xml b/xml/System.Diagnostics.Tracing/PollingCounter.xml index 0a75ccf96e0..2f0b5f4a0a2 100644 --- a/xml/System.Diagnostics.Tracing/PollingCounter.xml +++ b/xml/System.Diagnostics.Tracing/PollingCounter.xml @@ -18,7 +18,7 @@ in that it takes a callback function to collect metrics on its own rather than requiring the user to call every time. +`PollingCounter` differs from in that it takes a callback function to collect metrics on its own rather than requiring the user to call every time. ]]> @@ -80,4 +80,4 @@ For an example usage of inside - \ No newline at end of file + From 86219a84641b536e277d79c0752ddd0e019d65f9 Mon Sep 17 00:00:00 2001 From: Sung Yoon Whang Date: Mon, 5 Aug 2019 15:07:42 -0700 Subject: [PATCH 08/12] Address comments --- .../DiagnosticCounter.xml | 16 ++++---- .../EventCounter.xml | 2 +- .../IncrementingEventCounter.xml | 7 +++- .../IncrementingPollingCounter.xml | 12 +++--- .../PollingCounter.xml | 12 ++++-- xml/System.Diagnostics/Activity.xml | 26 ++++++------- xml/System.Diagnostics/ActivitySpanId.xml | 36 ++++++++---------- xml/System.Diagnostics/ActivityTraceFlags.xml | 4 +- xml/System.Diagnostics/ActivityTraceId.xml | 38 +++++++++---------- xml/System.Diagnostics/DiagnosticSource.xml | 14 +++---- 10 files changed, 81 insertions(+), 86 deletions(-) diff --git a/xml/System.Diagnostics.Tracing/DiagnosticCounter.xml b/xml/System.Diagnostics.Tracing/DiagnosticCounter.xml index 407d64a6a97..381b18c3c31 100644 --- a/xml/System.Diagnostics.Tracing/DiagnosticCounter.xml +++ b/xml/System.Diagnostics.Tracing/DiagnosticCounter.xml @@ -65,13 +65,13 @@ System.String - The display name of the counter. - To be added. + Gets or sets display name of the counter. + The display name of the counter. @@ -145,9 +145,9 @@ After being disposed, this counter will do nothing, and its resources will be re System.Diagnostics.Tracing.EventSource - The EventSource that this counter is attached to. - To be added. - + Gets the EventSource that this counter is attached to. + The EventSource that this counter is attached to. + To be added. @@ -166,8 +166,8 @@ After being disposed, this counter will do nothing, and its resources will be re System.String - The name of this counter. - To be added. + Gets the name of this counter. + The name of this counter. To be added. diff --git a/xml/System.Diagnostics.Tracing/EventCounter.xml b/xml/System.Diagnostics.Tracing/EventCounter.xml index 67811481804..7bdba0ff7d2 100644 --- a/xml/System.Diagnostics.Tracing/EventCounter.xml +++ b/xml/System.Diagnostics.Tracing/EventCounter.xml @@ -37,7 +37,7 @@ class, see the [Introduction Tutorial: How to measure performance for very frequent events using EventCounters](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md) topic. +For an example of how to use the class, see [Introduction Tutorial: How to measure performance for very frequent events using EventCounters](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md). ]]> diff --git a/xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml b/xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml index 10fe34c3f68..676fec424fa 100644 --- a/xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml +++ b/xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml @@ -70,11 +70,14 @@ System.TimeSpan - The rate at which this metric should be displayed as. + Gets or sets the rate at which this metric should be displayed as. + Gets or sets the rate at which this metric should be displayed diff --git a/xml/System.Diagnostics.Tracing/IncrementingPollingCounter.xml b/xml/System.Diagnostics.Tracing/IncrementingPollingCounter.xml index b0bd59e224b..55a2a218c7f 100644 --- a/xml/System.Diagnostics.Tracing/IncrementingPollingCounter.xml +++ b/xml/System.Diagnostics.Tracing/IncrementingPollingCounter.xml @@ -42,7 +42,7 @@ The name for this instance. - The object this instance is a part of. + The event source this instance is a part of. A method that will be used to poll the value. Initializes a new instance of the class. @@ -50,9 +50,9 @@ objects live as long as the that they are attached to unless they are explicitly disposed. -The method passed as a parameter is used for polling the values at the interval specified by the listener. This method is expected to return an incrementing float value; otherwise, an increment of a negative value may be reported. +`totalValueProvider` is a method used for polling the values at the interval specified by the listener. This method is expected to return an incrementing float value; otherwise, an increment of a negative value may be reported. -For an example usage of inside the runtime as one of the runtime performance counters, please refer to the CoreCLR source for runtime performance counter EventSource - [System.Runtime](https://github.com/dotnet/coreclr/blob/master/src/System.Private.CoreLib/src/System/Diagnostics/Eventing/RuntimeEventSource.cs). +For an example that uses inside the runtime as for runtime performance counters, see the CoreCLR source for [RuntimeEventSource](https://github.com/dotnet/coreclr/blob/master/src/System.Private.CoreLib/src/System/Diagnostics/Eventing/RuntimeEventSource.cs) on GitHub. ]]> @@ -74,11 +74,13 @@ For an example usage of System.TimeSpan - The rate at which this metric should be displayed as. + Gets or sets rate at which this metric should be displayed as. + The rate at which this metric should be displayed. diff --git a/xml/System.Diagnostics.Tracing/PollingCounter.xml b/xml/System.Diagnostics.Tracing/PollingCounter.xml index 2f0b5f4a0a2..0734e011166 100644 --- a/xml/System.Diagnostics.Tracing/PollingCounter.xml +++ b/xml/System.Diagnostics.Tracing/PollingCounter.xml @@ -17,6 +17,7 @@ Provides a variant of that collects and calculates similar statistics as . in that it takes a callback function to collect metrics on its own rather than requiring the user to call every time. @@ -46,12 +47,15 @@ A method that will be used to poll the value. Initializes a new instance of the class. - is a variant of where instead of the writer having to explicitly call `WriteMetric()` each time a value wants to be tracked, it takes in a callback method to poll for values. It polls and reports a value retrieved from calling `metricProvider` exactly once per the interval requested by the listener. + lives as long as the that it is attached to unless they are explicitly disposed. +## Remarks -For an example usage of inside the runtime as one of the runtime performance counters, please refer to the CoreCLR source for runtime performance counter EventSource - [System.Runtime](https://github.com/dotnet/coreclr/blob/master/src/System.Private.CoreLib/src/System/Diagnostics/Eventing/RuntimeEventSource.cs). + is a variant of that uses a callback method to poll for values rather than requiring the writer to explicitly call each time a value is tracked, `metricProvider` is a callback method that polls for values. The instance polls and reports a value retrieved by calling `metricProvider` exactly once per the interval requested by the listener. + +A lives as long as the that it is attached to unless it is explicitly disposed. + +For an example that uses inside the runtime for runtime performance counters, see the CoreCLR source for [RuntimeEventSource](https://github.com/dotnet/coreclr/blob/master/src/System.Private.CoreLib/src/System/Diagnostics/Eventing/RuntimeEventSource.cs) on GitHub. ]]> diff --git a/xml/System.Diagnostics/Activity.xml b/xml/System.Diagnostics/Activity.xml index ac7585e99db..0b5cfed8c7c 100644 --- a/xml/System.Diagnostics/Activity.xml +++ b/xml/System.Diagnostics/Activity.xml @@ -114,8 +114,7 @@ Note that has a "builder" pattern: you call t The baggage key. The baggage value. Updates the to have a new baggage item with the specified key and value. - - for convenient chaining. + for convenient chaining. The tag key. The tag value. Updates the to have a new tag with the provided and . . - - for convenient chaining. + for convenient chaining. or the The UTC stop time. Updates the to set its as the difference between and the specified stop time. - - for convenient chaining. + for convenient chaining. To be added. @@ -635,8 +632,7 @@ The root ID is a substring from the or the The ID of the parent operation. Updates this to indicate that the with an ID of caused this . - - for convenient chaining. + for convenient chaining. - The parent activity's . - The parent activity's . + The parent activity's TraceId. + The parent activity's SpanId. To be added. - Set the parent ID using the W3C convention using a TraceId and a SpanId. + Sets the parent ID using the W3C convention of a TraceId and a SpanId. for convenient chaining. @@ -705,8 +703,7 @@ This constructor has the advantage that no string manipulation is needed to set The start time in UTC. Sets the start time of this . - - for convenient chaining. + for convenient chaining. To be added. @@ -752,8 +749,7 @@ This constructor has the advantage that no string manipulation is needed to set Starts the activity. - - for convenient chaining. + for convenient chaining. are not all lower-case hexadecimal - The to compare to. - Determines whether two objects have the same value. - if has the same hex value as . + The instance to compare. + Determines whether this instance and the specified instance have the same value. + if has the same hex value as the current instance; otherwise, . To be added. @@ -214,9 +214,9 @@ The characters in are not all lower-case hexadecimal - The to compare to. - Determines whether two objects have the same value. - if is an instance of and has the same hex value as ; otherwise, . + The object to compare. + the current instance and a specified object, which also must be a instance, have the same value. + if is an instance of and has the same hex value as the current instance; otherwise, . To be added. @@ -237,8 +237,8 @@ The characters in are not all lower-case hexadecimal - Returns the hash of the SpanId. - The hash of the SpanId. + Returns the hash code of the SpanId. + The hash code of the SpanId. To be added. @@ -262,12 +262,10 @@ The characters in are not all lower-case hexadecimal - The first to compare. - The second to compare. - Determines whether two specified ActivitySpanIds have the same value. - - if the SpanId of is the same as the SpanId of ; otherwise, . - + The first instance to compare. + The second instance to compare. + Determines whether two specified instances have the same value. + if the SpanId of is the same as the SpanId of ; otherwise, . To be added. @@ -291,12 +289,10 @@ The characters in are not all lower-case hexadecimal - The first to compare. - The second to compare. - Compare with another instance of . - - if the SpanId of is different from the SpanId of ; otherwise, . - + The first instance to compare. + The second instance to compare. + Determine whether two specified instances have unequal values. + if the SpanId of is different from the SpanId of ; otherwise, . To be added. diff --git a/xml/System.Diagnostics/ActivityTraceFlags.xml b/xml/System.Diagnostics/ActivityTraceFlags.xml index 1e4603a2652..474c96a6ecc 100644 --- a/xml/System.Diagnostics/ActivityTraceFlags.xml +++ b/xml/System.Diagnostics/ActivityTraceFlags.xml @@ -45,7 +45,7 @@ An `ActivityTraceFflags` value is returned by the 0 - The activity has not been marked with anything. + The activity has not been marked. @@ -65,7 +65,7 @@ An `ActivityTraceFflags` value is returned by the 1 - Indicates that the Activity (or more likley its parents) has been marked as useful to record. + The activity (or more likely its parents) has been marked as useful to record. diff --git a/xml/System.Diagnostics/ActivityTraceId.xml b/xml/System.Diagnostics/ActivityTraceId.xml index 89f1f6b67f2..ab1a0aa8b6e 100644 --- a/xml/System.Diagnostics/ActivityTraceId.xml +++ b/xml/System.Diagnostics/ActivityTraceId.xml @@ -189,9 +189,9 @@ The characters in are not all lower-case hexadecimal - The to compare to. - Compare with another instance of . - if has the same hex value as . + The instance to compare. + Determines whether the current instance and a specified are equal. + if has the same hex value as the current instance; otherwise, . To be added. @@ -214,9 +214,9 @@ The characters in are not all lower-case hexadecimal - The to compare to. - Determines whether two objects have the same value. - if is an instance of and has the same hex value as ; otherwise, . + The object to compare. + Determines whether this instance and a specified object, which must also be an instance, have the same value. + if is an instance of and has the same hex value as the current instance; otherwise, . To be added. @@ -237,8 +237,8 @@ The characters in are not all lower-case hexadecimal - Returns the hash of the TraceId. - The hash of the TraceId. + Returns the hash code of the TraceId. + The hash code of the TraceId. To be added. @@ -262,12 +262,10 @@ The characters in are not all lower-case hexadecimal - The first to compare. - The second to compare. - Determines whether two specified ActivityTraceIds have the same value. - - if the TraceId of is the same as the TraceId of ; otherwise, . - + The first instance to compare. + The second instance to compare. + Determines whether two specified instances have the same value. + if the TraceId of is the same as the TraceId of ; otherwise, . @@ -290,12 +288,10 @@ The characters in are not all lower-case hexadecimal - The first to compare. - The second to compare. - Determines whether two specified ActivityTraceIds have the same value. - - if the TraceId of is the different from the TraceId of ; otherwise, . - + The first instance to compare. + The second instance to compare. + Determines whether two specified instances have the same value. + if the TraceId of is different from the TraceId of ; otherwise, . @@ -316,7 +312,7 @@ The characters in are not all lower-case hexadecimal Returns a 16-character hexadecimal string that represents this span ID. - The 32-character hecxadecimal string representation of this trace ID. + The 32-character hexadecimal string representation of this trace ID. To be added. diff --git a/xml/System.Diagnostics/DiagnosticSource.xml b/xml/System.Diagnostics/DiagnosticSource.xml index 5871336311d..c80ef9c116e 100644 --- a/xml/System.Diagnostics/DiagnosticSource.xml +++ b/xml/System.Diagnostics/DiagnosticSource.xml @@ -71,8 +71,7 @@ The name of the event being written. Verifies if the notification event is enabled. - - if the notification event is enabled, otherwise. + if the notification event is enabled, otherwise. An object that represents the additional context for IsEnabled. Consumers should expect to receive which may indicate that producer called pure IsEnabled(string) to check if consumer wants to get notifications for such events at all. Based on that, producer may call IsEnabled(string, object, object) again with non- context. Optional. An object that represents the additional context for IsEnabled. by default. Consumers should expect to receive which may indicate that producer called pure IsEnabled(string) or producer passed all necessary context in . Verifies it the notification event is enabled. - - if the notification event is enabled, otherwise. + if the notification event is enabled, otherwise. and the ougoing request logic at the instrumentation site. However, the instrumenation site can't handle policy (for example, whether activity information should be disabled or written in an older format for compatibility reasons). +To the extent possible, this should be done by the instrumentation site, because there is a contract between an and the ougoing request logic at the instrumentation site. However, the instrumentation site can't handle policy (for example, whether activity information should be disabled or written in an older format for compatibility reasons). For this, the instrumentation site needs to call back out to the logging system and ask it to resolve policy. This is the purpose of the `OnActivityExport` method. The `OnActivityExport` method is given the as well as a payload object that represents the outgoing request. A subscriber then has the ability to update the outgoing request before it is sent. -Note that this method is rarely used at instrumentation sites (only those sites that are on an outgoing boundary of the process). Moreover, typically the default policy that the instrumenation site performs (for example, to transfer all activity state in a +Note that this method is rarely used at instrumentation sites (only those sites that are on an outgoing boundary of the process). Moreover, typically the default policy that the instrumentation site performs (for example, to transfer all activity state in a particular outgoing convention) is likely to be fine. This method is only for cases where that is a problem. Thus, this method should be used very rarely and is mostly here for symetry with `OnActivityImport` and future-proofing. Note that `payload` is typed as an here, but any particular instrumentation site and subscriber should know the type of the payload and thus cast and decode it if necessary. @@ -186,7 +184,7 @@ Note that `payload` is typed as an here, but any particular and the incomming request logic at the instrumentation site. However, the instrumentation site can't handle policy. (For example, if sampling is done, exactly which requests should be sampled?) In these cases, the instrumentation site needs to call back out to the logging system and ask it to resolve policy (for example, to decide if the activity's "sampling" bit should be set). This is the purpose of the `OnActivityImport` method. It is given the activity as well as a payload object that represents the incomming request. The subscribers to the then have the opportunity to update this activity as desired. From 3e54abaab879ee870399f87999fa27a87358e302 Mon Sep 17 00:00:00 2001 From: Sung Yoon Whang Date: Mon, 5 Aug 2019 15:10:22 -0700 Subject: [PATCH 09/12] address more comments --- xml/System.Diagnostics.Tracing/EventCounter.xml | 2 +- xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml | 2 +- xml/System.Diagnostics/Activity.xml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/xml/System.Diagnostics.Tracing/EventCounter.xml b/xml/System.Diagnostics.Tracing/EventCounter.xml index 7bdba0ff7d2..c9af49a6c06 100644 --- a/xml/System.Diagnostics.Tracing/EventCounter.xml +++ b/xml/System.Diagnostics.Tracing/EventCounter.xml @@ -164,7 +164,7 @@ For an example of how to use the method, see the [Introduction Tutorial: How to measure performance for very frequent events using EventCounters](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md) topic. + For an example of how to use the method, see [Introduction Tutorial: How to measure performance for very frequent events using EventCounters](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md). ]]> diff --git a/xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml b/xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml index 676fec424fa..75f82b81719 100644 --- a/xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml +++ b/xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml @@ -48,7 +48,7 @@ live as long as the that they are attached to unless they are explicitly disposed. + live as long as the that they are attached to unless they are explicitly disposed. ]]> diff --git a/xml/System.Diagnostics/Activity.xml b/xml/System.Diagnostics/Activity.xml index 0b5cfed8c7c..4b8065e25a8 100644 --- a/xml/System.Diagnostics/Activity.xml +++ b/xml/System.Diagnostics/Activity.xml @@ -673,7 +673,7 @@ This property should only be used in 'boundary' scenarios where an Provides the ability to collect statistics for very frequent events through the class. - class, see [Introduction Tutorial: How to measure performance for very frequent events using EventCounters](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md). diff --git a/xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml b/xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml index 75f82b81719..3b46a8289a3 100644 --- a/xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml +++ b/xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml @@ -18,6 +18,8 @@ live as long as the that they are attached to unless they are explicitly disposed. ]]> diff --git a/xml/System.Diagnostics.Tracing/IncrementingPollingCounter.xml b/xml/System.Diagnostics.Tracing/IncrementingPollingCounter.xml index 55a2a218c7f..e955a3cec9b 100644 --- a/xml/System.Diagnostics.Tracing/IncrementingPollingCounter.xml +++ b/xml/System.Diagnostics.Tracing/IncrementingPollingCounter.xml @@ -17,8 +17,16 @@ Provides a variant of for variables that are ever-increasing, such as the number of exceptions in the runtime. , this takes in a polling callback that it can call to update its own metric periodically. + +## Remarks + + objects live as long as the that they are attached to unless they are explicitly disposed. + +`totalValueProvider` is a method used for polling the values at the interval specified by the listener. This method is expected to return an incrementing float value; otherwise, an increment of a negative value may be reported. + +`IncrementingPollingCounter` does not calculate statistics like mean and standard deviation because it only accumulates the counter value. Unlike , this takes in a polling callback that it can call to update its own metric periodically. + +For an example that uses inside the runtime as for runtime performance counters, see the CoreCLR source for [RuntimeEventSource](https://github.com/dotnet/coreclr/blob/master/src/System.Private.CoreLib/src/System/Diagnostics/Eventing/RuntimeEventSource.cs) on GitHub. ]]> @@ -45,17 +53,7 @@ The event source this instance is a part of. A method that will be used to poll the value. Initializes a new instance of the class. - - objects live as long as the that they are attached to unless they are explicitly disposed. - -`totalValueProvider` is a method used for polling the values at the interval specified by the listener. This method is expected to return an incrementing float value; otherwise, an increment of a negative value may be reported. - -For an example that uses inside the runtime as for runtime performance counters, see the CoreCLR source for [RuntimeEventSource](https://github.com/dotnet/coreclr/blob/master/src/System.Private.CoreLib/src/System/Diagnostics/Eventing/RuntimeEventSource.cs) on GitHub. - - ]]> - + To be added. diff --git a/xml/System.Diagnostics.Tracing/PollingCounter.xml b/xml/System.Diagnostics.Tracing/PollingCounter.xml index 0734e011166..457261323d8 100644 --- a/xml/System.Diagnostics.Tracing/PollingCounter.xml +++ b/xml/System.Diagnostics.Tracing/PollingCounter.xml @@ -17,10 +17,17 @@ Provides a variant of that collects and calculates similar statistics as . is a variant of that uses a callback method to poll for values rather than requiring the writer to explicitly call each time a value is tracked, `metricProvider` is a callback method that polls for values. The instance polls and reports a value retrieved by calling `metricProvider` exactly once per the interval requested by the listener. + +A lives as long as the that it is attached to unless it is explicitly disposed. + `PollingCounter` differs from in that it takes a callback function to collect metrics on its own rather than requiring the user to call every time. +For an example that uses inside the runtime for runtime performance counters, see the CoreCLR source for [RuntimeEventSource](https://github.com/dotnet/coreclr/blob/master/src/System.Private.CoreLib/src/System/Diagnostics/Eventing/RuntimeEventSource.cs) on GitHub. + ]]> @@ -46,19 +53,7 @@ The event source. A method that will be used to poll the value. Initializes a new instance of the class. - - is a variant of that uses a callback method to poll for values rather than requiring the writer to explicitly call each time a value is tracked, `metricProvider` is a callback method that polls for values. The instance polls and reports a value retrieved by calling `metricProvider` exactly once per the interval requested by the listener. - -A lives as long as the that it is attached to unless it is explicitly disposed. - -For an example that uses inside the runtime for runtime performance counters, see the CoreCLR source for [RuntimeEventSource](https://github.com/dotnet/coreclr/blob/master/src/System.Private.CoreLib/src/System/Diagnostics/Eventing/RuntimeEventSource.cs) on GitHub. - - ]]> - + To be added. diff --git a/xml/System.Diagnostics/Activity.xml b/xml/System.Diagnostics/Activity.xml index 4b8065e25a8..75af97709cd 100644 --- a/xml/System.Diagnostics/Activity.xml +++ b/xml/System.Diagnostics/Activity.xml @@ -19,16 +19,18 @@ Represents an operation with context to be used for logging. - property. Activities should be created by calling the constructor, configured as necessary, and then started with the method, which maintains parent-child relationships for the activities and sets . - + When an activity is finished, it should be stopped with the method. - + No `Activity` methods allow exceptions to escape as a response to bad inputs. They are thrown and caught (which allows debuggers and monitors to see the error), but the exception is suppressed, and the operation does something reasonable (typically it does nothing). ]]> diff --git a/xml/System.Diagnostics/ActivityTraceFlags.xml b/xml/System.Diagnostics/ActivityTraceFlags.xml index 474c96a6ecc..8091bf7a3ca 100644 --- a/xml/System.Diagnostics/ActivityTraceFlags.xml +++ b/xml/System.Diagnostics/ActivityTraceFlags.xml @@ -20,7 +20,9 @@ Specifies flags defined by the W3C standard that are associated with an activity. - property. diff --git a/xml/System.Diagnostics/ActivityTraceId.xml b/xml/System.Diagnostics/ActivityTraceId.xml index ab1a0aa8b6e..48838cf27ae 100644 --- a/xml/System.Diagnostics/ActivityTraceId.xml +++ b/xml/System.Diagnostics/ActivityTraceId.xml @@ -22,6 +22,8 @@ property. Because an `ActivityTraceId` is a structure that contains 16 bytes, it can be passed easily by reference. `ActivityTraceId` contains methods for converting to and from its hexadecimal string representation, tries to avoid changing formats until it has to, and caches its string representation after it is created. It is mostly useful as an exchange type. diff --git a/xml/System.Diagnostics/DiagnosticListener.xml b/xml/System.Diagnostics/DiagnosticListener.xml index 1e5b314e4f0..3432a266db1 100644 --- a/xml/System.Diagnostics/DiagnosticListener.xml +++ b/xml/System.Diagnostics/DiagnosticListener.xml @@ -28,8 +28,13 @@ Provides an implementation of the abstract class that represents a named place to which a source sends its information (events). - + method so notifications can be forwarded arbitrarily. Thus, its job is to forward things from the producer to all the listeners (multi-casting). Generally, you should not be making your own but use the default, so that notifications are as public as possible. + For more information on the and classes, see [DiagnosticSource User's Guide](https://github.com/dotnet/corefx/blob/d3942d4671919edb0cca6ddc1840190f524a809d/src/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md). ]]> @@ -59,13 +64,7 @@ For more information on the and The name of this . Creates a new . - - method so notifications can be forwarded arbitrarily. Thus, its job is to forward things from the producer to all the listeners (multi-casting). Generally, you should not be making your own but use the default, so that notifications are as public as possible. - - ]]> - + To be added. diff --git a/xml/System.Diagnostics/DiagnosticSource.xml b/xml/System.Diagnostics/DiagnosticSource.xml index c80ef9c116e..eb198237683 100644 --- a/xml/System.Diagnostics/DiagnosticSource.xml +++ b/xml/System.Diagnostics/DiagnosticSource.xml @@ -41,7 +41,7 @@ - To be added. + Initializes an instance of the class. To be added. From b4d6acf02f53822d9fd1dc5d5b934f1eabfe9b62 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Wed, 7 Aug 2019 12:17:53 -0700 Subject: [PATCH 11/12] Fixed bad API links --- xml/System.Diagnostics/ActivitySpanId.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/xml/System.Diagnostics/ActivitySpanId.xml b/xml/System.Diagnostics/ActivitySpanId.xml index e481e933617..46373f355c7 100644 --- a/xml/System.Diagnostics/ActivitySpanId.xml +++ b/xml/System.Diagnostics/ActivitySpanId.xml @@ -190,7 +190,7 @@ The characters in are not all lower-case hexadecimal The instance to compare. - Determines whether this instance and the specified instance have the same value. + Determines whether this instance and the specified instance have the same value. if has the same hex value as the current instance; otherwise, . To be added. @@ -215,8 +215,8 @@ The characters in are not all lower-case hexadecimal The object to compare. - the current instance and a specified object, which also must be a instance, have the same value. - if is an instance of and has the same hex value as the current instance; otherwise, . + the current instance and a specified object, which also must be an instance, have the same value. + if is an instance of and has the same hex value as the current instance; otherwise, . To be added. From e9f206e7c3841514cbaac7fe7065ccdeedd05fd7 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Wed, 7 Aug 2019 12:19:23 -0700 Subject: [PATCH 12/12] Fixed bad API links --- xml/System.Diagnostics/ActivityTraceId.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/xml/System.Diagnostics/ActivityTraceId.xml b/xml/System.Diagnostics/ActivityTraceId.xml index 48838cf27ae..d9ec586eac1 100644 --- a/xml/System.Diagnostics/ActivityTraceId.xml +++ b/xml/System.Diagnostics/ActivityTraceId.xml @@ -192,7 +192,7 @@ The characters in are not all lower-case hexadecimal The instance to compare. - Determines whether the current instance and a specified are equal. + Determines whether the current instance and a specified are equal. if has the same hex value as the current instance; otherwise, . To be added. @@ -217,8 +217,8 @@ The characters in are not all lower-case hexadecimal The object to compare. - Determines whether this instance and a specified object, which must also be an instance, have the same value. - if is an instance of and has the same hex value as the current instance; otherwise, . + Determines whether this instance and a specified object, which must also be an instance, have the same value. + if is an instance of and has the same hex value as the current instance; otherwise, . To be added.