Skip to content

Dev/suwhang/system.diagnostics #2901

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Aug 7, 2019
Merged

Dev/suwhang/system.diagnostics #2901

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
1663f0a
System.Diagnostics.Tracing.*
sywhang Aug 1, 2019
2aaa659
System.Diagnotics.Activity*
sywhang Aug 1, 2019
309e781
DiagnosticSource
sywhang Aug 1, 2019
3a83949
Update Activity.xml
Aug 1, 2019
7452a4f
Update ActivitySpanId.xml
Aug 1, 2019
77532d4
Update ActivityTraceId.xml
Aug 1, 2019
293577c
Changed crefs to xrefs
Aug 2, 2019
86219a8
Address comments
sywhang Aug 5, 2019
3e54aba
address more comments
sywhang Aug 5, 2019
6a3f94d
Move remarks from .ctor to type
carlossanlop Aug 7, 2019
b4d6acf
Fixed bad API links
Aug 7, 2019
e9f206e
Fixed bad API links
Aug 7, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions xml/System.Diagnostics.Tracing/DiagnosticCounter.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,9 +65,17 @@
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>The display name of the counter.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks

The DisplayName is a property that is used as a more display friendly name for the consumer side of the metrics. For example, a counter named "gen-0-gc-count" is better displayed as "Gen 0 GC Count". To do so, `DisplayName` can be used to be reported as part of the payload.

]]></format>

</remarks>
</Docs>
</Member>
<Member MemberName="DisplayUnits">
Expand Down Expand Up @@ -137,9 +145,9 @@ After being disposed, this counter will do nothing, and its resources will be re
<ReturnType>System.Diagnostics.Tracing.EventSource</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>The EventSource that this counter is attached to.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<remarks></remarks>
</Docs>
</Member>
<Member MemberName="Name">
Expand All @@ -158,7 +166,7 @@ After being disposed, this counter will do nothing, and its resources will be re
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>The name of this counter.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand Down
15 changes: 11 additions & 4 deletions xml/System.Diagnostics.Tracing/EventCounter.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
<summary>Provides the ability to collect statistics for very frequent events through the <see cref="T:System.Diagnostics.Tracing.EventSource" /> class.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
## Remarks

For an example of how to use the <xref:System.Diagnostics.Tracing.EventCounter> 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.

Expand Down Expand Up @@ -158,9 +158,16 @@ For an example of how to use the <xref:System.Diagnostics.Tracing.EventCounter>
<Parameter Name="value" Type="System.Double" Index="0" FrameworkAlternate="netcore-3.0" />
</Parameters>
<Docs>
<param name="value">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<param name="value">The value to be written.</param>
<summary>Writes the metric if performance counters are on.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks

For an example of how to use the <xref:System.Diagnostics.Tracing.EventCounter.WriteMetric(System.Single)> 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.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="WriteMetric">
Expand Down
17 changes: 12 additions & 5 deletions xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,9 @@
<remarks>
<format type="text/markdown"><![CDATA[

`IncrementingEventCounter` does not calculate statistics like mean or standard deviation because it only accumulates the counter value.
`IncrementingEventCounter` is used for keeping track of values that are always increasing, such as the total number of requests, the total number of exceptions thrown, etc. For such metrics, simply reporting the total value is not necessarily useful for monitoring its health. For example, keeping track of how many bytes have been allocated in total for the entire duration of the process is not useful for diagnosing any potential issues from allocating too much memory. A metric that would help us is how many bytes were allocated in the past minute, hour, or some arbitrary time interval, and not the entire duration of the process. `IncrementingEventCounter` can be used to keep track of and report just the increments over a time interval that was specified by the consumer of the metric.

`IncrementingEventCounter` does not calculate statistics like mean or standard deviation because it only keeps track of the increments over a period of time.

]]></format>
</remarks>
Expand Down Expand Up @@ -46,7 +48,7 @@
<remarks>
<format type="text/markdown"><![CDATA[

Incrementing event counters live as long as the <see cref="T:System.Diagnostics.Tracing.EventSource" /> that they are attached to unless they are explicitly disposed.
<xref:System.Diagnostics.Tracing.IncrementingEventCounter> live as long as the <see cref="T:System.Diagnostics.Tracing.EventSource" /> that they are attached to unless they are explicitly disposed.

]]></format>
</remarks>
Expand All @@ -68,9 +70,14 @@ Incrementing event counters live as long as the <see cref="T:System.Diagnostics.
<ReturnType>System.TimeSpan</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<summary>The rate at which this metric should be displayed as.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

This allows counters to have a rate at which this metric should be displayed at. It is included as part of the payload as a string.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="Increment">
Expand Down
19 changes: 14 additions & 5 deletions xml/System.Diagnostics.Tracing/IncrementingPollingCounter.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,14 +42,18 @@
</Parameters>
<Docs>
<param name="name">The name for this <see cref="T:System.Diagnostics.Tracing.IncrementingPollingCounter" /> instance.</param>
<param name="eventSource">The event source.</param>
<param name="totalValueProvider">To be added.</param>
<param name="eventSource">The <see cref="T:System.Diagnostics.Tracing.EventSource" /> object this instance is a part of.</param>
<param name="totalValueProvider">A method that will be used to poll the value.</param>
<summary>Initializes a new instance of the <see cref="T:System.Diagnostics.Tracing.IncrementingPollingCounter" /> class.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

<xref:System.Diagnostics.Tracing.IncrementingPollingCounter> objects live as long as the <xref:System.Diagnostics.Tracing.EventSource> 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 <xref:System.Diagnostics.Tracing.IncrementingPollingCounter> 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).

]]></format>
</remarks>
</Docs>
Expand All @@ -70,9 +74,14 @@
<ReturnType>System.TimeSpan</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<summary>The rate at which this metric should be displayed as.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

This allows counters to have a rate at which this metric should be displayed at. It is included as part of the payload as a string.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="ToString">
Expand Down
7 changes: 5 additions & 2 deletions xml/System.Diagnostics.Tracing/PollingCounter.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,12 +43,15 @@
<Docs>
<param name="name">The name for this <see cref="T:System.Diagnostics.Tracing.PollingCounter" /> instance.</param>
<param name="eventSource">The event source.</param>
<param name="metricProvider">To be added.</param>
<param name="metricProvider">A method that will be used to poll the value.</param>
<summary>Initializes a new instance of the <see cref="T:System.Diagnostics.Tracing.PollingCounter" /> class.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
<xref:System.Diagnostics.Tracing.PollingCounter> is a variant of <xref:System.Diagnostics.Tracing.EventCounter> 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 <see cref="T:System.Diagnostics.Tracing.EventSource" /> that they are attached to unless they are explicitly disposed.
<xref:System.Diagnostics.Tracing.PollingCounter> lives as long as the <see cref="T:System.Diagnostics.Tracing.EventSource" /> that it is attached to unless they are explicitly disposed.

For an example usage of <xref:System.Diagnostics.Tracing.PollingCounter> 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).

]]></format>
</remarks>
Expand Down
18 changes: 13 additions & 5 deletions xml/System.Diagnostics/Activity.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -667,12 +667,20 @@ This property should only be used in 'boundary' scenarios where an <see cref="T:
<Parameter Name="activityTraceFlags" Type="System.Diagnostics.ActivityTraceFlags" Index="2" FrameworkAlternate="netcore-3.0" />
</Parameters>
<Docs>
<param name="traceId">To be added.</param>
<param name="spanId">To be added.</param>
<param name="traceId">The parent activity's <see cref="T:System.Diagnostics.ActivityTraceId" />.</param>
<param name="spanId">The parent activity's <see cref="T:System.Diagnostics.ActivitySpanId" />.</param>
<param name="activityTraceFlags">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<summary>Set the parent ID using the W3C convention using a TraceId and a SpanId.</summary>
<returns>
<see langword="this" /> for convenient chaining.</returns>
</returns>
<remarks>
<format type="text/markdown"><![CDATA[

This constructor has the advantage that no string manipulation is needed to set the ID.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="SetStartTime">
Expand Down
36 changes: 20 additions & 16 deletions xml/System.Diagnostics/ActivitySpanId.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,9 +189,9 @@ The characters in <paramref name="idData" /> are not all lower-case hexadecimal
<Parameter Name="spanId" Type="System.Diagnostics.ActivitySpanId" />
</Parameters>
<Docs>
<param name="spanId">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="spanId">The <see cref="T:System.Diagnostics.Tracing.ActivitySpanId" /> to compare to.</param>
<summary>Determines whether two <see cref="T:System.Diagnostics.Tracing.ActivitySpanId" /> objects have the same value.</summary>
<returns><see langword="true" /> if <paramref name="spanId" /> has the same hex value as <see langword="this" />.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -214,9 +214,9 @@ The characters in <paramref name="idData" /> are not all lower-case hexadecimal
<Parameter Name="obj" Type="System.Object" />
</Parameters>
<Docs>
<param name="obj">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="obj">The <see cref="T:System.Object" /> to compare to.</param>
<summary>Determines whether two <see cref="T:System.Diagnostics.Tracing.ActivitySpanId" /> objects have the same value.</summary>
<returns><see langword="true" /> if <paramref name="obj" /> is an instance of <see cref="T:System.Diagnostics.Tracing.ActivitySpanId" /> and has the same hex value as <see langword="this" />; otherwise, <see langword="false" />.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -237,8 +237,8 @@ The characters in <paramref name="idData" /> are not all lower-case hexadecimal
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<summary>Returns the hash of the SpanId.</summary>
<returns>The hash of the SpanId.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -262,10 +262,12 @@ The characters in <paramref name="idData" /> are not all lower-case hexadecimal
<Parameter Name="spandId2" Type="System.Diagnostics.ActivitySpanId" />
</Parameters>
<Docs>
<param name="spanId1">To be added.</param>
<param name="spandId2">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="spanId1">The first <see cref="T:System.Diagnostics.Tracing.ActivitySpanId" /> to compare.</param>
<param name="spandId2">The second <see cref="T:System.Diagnostics.Tracing.ActivitySpanId" /> to compare.</param>
<summary>Determines whether two specified ActivitySpanIds have the same value.</summary>
<returns>
<see langword="true" /> if the SpanId of <paramref name="spanId1" /> is the same as the SpanId of <paramref name="spandId2" />; otherwise, <see langword="false" />.
</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -289,10 +291,12 @@ The characters in <paramref name="idData" /> are not all lower-case hexadecimal
<Parameter Name="spandId2" Type="System.Diagnostics.ActivitySpanId" />
</Parameters>
<Docs>
<param name="spanId1">To be added.</param>
<param name="spandId2">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="spanId1">The first <see cref="T:System.Diagnostics.Tracing.ActivitySpanId" /> to compare.</param>
<param name="spandId2">The second <see cref="T:System.Diagnostics.Tracing.ActivitySpanId" /> to compare.</param>
<summary>Compare <see langword="this"> with another instance of <see cref="T:System.Diagnostics.Tracing.ActivitySpanId" />.</summary>
<returns>
<see langword="true" /> if the SpanId of <paramref name="spanId1" /> is different from the SpanId of <paramref name="spandId2" />; otherwise, <see langword="false" />.
</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
4 changes: 2 additions & 2 deletions xml/System.Diagnostics/ActivityTraceFlags.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ An `ActivityTraceFflags` value is returned by the <xref:System.Diagnostics.Activ
</ReturnValue>
<MemberValue>0</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>The activity has not been marked with anything.</summary>
</Docs>
</Member>
<Member MemberName="Recorded">
Expand All @@ -65,7 +65,7 @@ An `ActivityTraceFflags` value is returned by the <xref:System.Diagnostics.Activ
</ReturnValue>
<MemberValue>1</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>Indicates that the Activity (or more likley its parents) has been marked as useful to record.</summary>
</Docs>
</Member>
</Members>
Expand Down
Loading