Skip to content

Commit 9eeeaef

Browse files
sywhangRon Petrusha
sywhang
authored and
Ron Petrusha
committed
Dev/suwhang/system.diagnostics (#2901)
* System.Diagnostics.Tracing.* * System.Diagnotics.Activity* * DiagnosticSource * Update Activity.xml * Update ActivitySpanId.xml * Update ActivityTraceId.xml * Changed crefs to xrefs * Address comments * address more comments * Move remarks from .ctor to type * Fixed bad API links * Fixed bad API links
1 parent 7360b5f commit 9eeeaef

11 files changed

+176
-131
lines changed

‎xml/System.Diagnostics.Tracing/DiagnosticCounter.xml

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -65,9 +65,18 @@
6565
<ReturnType>System.String</ReturnType>
6666
</ReturnValue>
6767
<Docs>
68-
<summary>To be added.</summary>
69-
<value>To be added.</value>
70-
<remarks>To be added.</remarks>
68+
<summary>Gets or sets display name of the counter.</summary>
69+
<value>The display name of the counter.</value>
70+
<remarks>
71+
<format type="text/markdown"><![CDATA[
72+
73+
## Remarks
74+
75+
The `DisplayName` provides 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.
76+
77+
]]></format>
78+
79+
</remarks>
7180
</Docs>
7281
</Member>
7382
<Member MemberName="DisplayUnits">
@@ -137,8 +146,8 @@ After being disposed, this counter will do nothing, and its resources will be re
137146
<ReturnType>System.Diagnostics.Tracing.EventSource</ReturnType>
138147
</ReturnValue>
139148
<Docs>
140-
<summary>To be added.</summary>
141-
<value>To be added.</value>
149+
<summary>Gets the EventSource that this counter is attached to.</summary>
150+
<value>The EventSource that this counter is attached to.</value>
142151
<remarks>To be added.</remarks>
143152
</Docs>
144153
</Member>
@@ -158,8 +167,8 @@ After being disposed, this counter will do nothing, and its resources will be re
158167
<ReturnType>System.String</ReturnType>
159168
</ReturnValue>
160169
<Docs>
161-
<summary>To be added.</summary>
162-
<value>To be added.</value>
170+
<summary>Gets the name of this counter.</summary>
171+
<value>The name of this counter.</value>
163172
<remarks>To be added.</remarks>
164173
</Docs>
165174
</Member>

‎xml/System.Diagnostics.Tracing/EventCounter.xml

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,11 @@
3434
<Docs>
3535
<summary>Provides the ability to collect statistics for very frequent events through the <see cref="T:System.Diagnostics.Tracing.EventSource" /> class.</summary>
3636
<remarks>
37-
<format type="text/markdown"><![CDATA[
38-
## Remarks
37+
<format type="text/markdown"><![CDATA[
3938
40-
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.
39+
## Remarks
40+
41+
For an example of how to use the <xref:System.Diagnostics.Tracing.EventCounter> 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).
4142
4243
]]></format>
4344
</remarks>
@@ -158,9 +159,16 @@ For an example of how to use the <xref:System.Diagnostics.Tracing.EventCounter>
158159
<Parameter Name="value" Type="System.Double" Index="0" FrameworkAlternate="netcore-3.0" />
159160
</Parameters>
160161
<Docs>
161-
<param name="value">To be added.</param>
162-
<summary>To be added.</summary>
163-
<remarks>To be added.</remarks>
162+
<param name="value">The value to be written.</param>
163+
<summary>Writes the metric if performance counters are on.</summary>
164+
<remarks>
165+
<format type="text/markdown"><![CDATA[
166+
## Remarks
167+
168+
For an example of how to use the <xref:System.Diagnostics.Tracing.EventCounter.WriteMetric(System.Single)> 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).
169+
170+
]]></format>
171+
</remarks>
164172
</Docs>
165173
</Member>
166174
<Member MemberName="WriteMetric">

‎xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,11 @@
1818
<remarks>
1919
<format type="text/markdown"><![CDATA[
2020
21-
`IncrementingEventCounter` does not calculate statistics like mean or standard deviation because it only accumulates the counter value.
21+
## Remarks
22+
23+
`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.
24+
25+
`IncrementingEventCounter` does not calculate statistics like mean or standard deviation because it only keeps track of the increments over a period of time.
2226
2327
]]></format>
2428
</remarks>
@@ -46,7 +50,9 @@
4650
<remarks>
4751
<format type="text/markdown"><![CDATA[
4852
49-
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.
53+
## Remarks
54+
55+
<xref:System.Diagnostics.Tracing.IncrementingEventCounter> live as long as the <xref:System.Diagnostics.Tracing.EventSource> that they are attached to unless they are explicitly disposed.
5056
5157
]]></format>
5258
</remarks>
@@ -68,9 +74,17 @@ Incrementing event counters live as long as the <see cref="T:System.Diagnostics.
6874
<ReturnType>System.TimeSpan</ReturnType>
6975
</ReturnValue>
7076
<Docs>
71-
<summary>To be added.</summary>
72-
<value>To be added.</value>
73-
<remarks>To be added.</remarks>
77+
<summary>Gets or sets the rate at which this metric should be displayed as.</summary>
78+
<value>Gets or sets the rate at which this metric should be displayed</value>
79+
<remarks>
80+
<format type="text/markdown"><![CDATA[
81+
82+
## Remarks
83+
84+
The value of the `DisplayRateTimeScale` property is included as a string in the payload.
85+
86+
]]></format>
87+
</remarks>
7488
</Docs>
7589
</Member>
7690
<Member MemberName="Increment">

‎xml/System.Diagnostics.Tracing/IncrementingPollingCounter.xml

Lines changed: 23 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,16 @@
1717
<summary>Provides a variant of <see cref="T:System.Diagnostics.Tracing.EventCounter" /> for variables that are ever-increasing, such as the number of exceptions in the runtime.</summary>
1818
<remarks>
1919
<format type="text/markdown"><![CDATA[
20-
21-
`IncrementingPollingCounter` does not calculate statistics like mean and standard deviation because it only accumulates the counter value. Unlike <see cref="T:System.Diagnostics.Tracing.IncrementingEventCounter" />, this takes in a polling callback that it can call to update its own metric periodically.
20+
21+
## Remarks
22+
23+
<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.
24+
25+
`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.
26+
27+
`IncrementingPollingCounter` does not calculate statistics like mean and standard deviation because it only accumulates the counter value. Unlike <xref:System.Diagnostics.Tracing.IncrementingEventCounter>, this takes in a polling callback that it can call to update its own metric periodically.
28+
29+
For an example that uses <xref:System.Diagnostics.Tracing.IncrementingPollingCounter> 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.
2230
2331
]]></format>
2432
</remarks>
@@ -42,16 +50,10 @@
4250
</Parameters>
4351
<Docs>
4452
<param name="name">The name for this <see cref="T:System.Diagnostics.Tracing.IncrementingPollingCounter" /> instance.</param>
45-
<param name="eventSource">The event source.</param>
46-
<param name="totalValueProvider">To be added.</param>
53+
<param name="eventSource">The event source this instance is a part of.</param>
54+
<param name="totalValueProvider">A method that will be used to poll the value.</param>
4755
<summary>Initializes a new instance of the <see cref="T:System.Diagnostics.Tracing.IncrementingPollingCounter" /> class.</summary>
48-
<remarks>
49-
<format type="text/markdown"><![CDATA[
50-
51-
<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.
52-
53-
]]></format>
54-
</remarks>
56+
<remarks>To be added.</remarks>
5557
</Docs>
5658
</Member>
5759
<Member MemberName="DisplayRateTimeScale">
@@ -70,9 +72,16 @@
7072
<ReturnType>System.TimeSpan</ReturnType>
7173
</ReturnValue>
7274
<Docs>
73-
<summary>To be added.</summary>
74-
<value>To be added.</value>
75-
<remarks>To be added.</remarks>
75+
<summary>Gets or sets rate at which this metric should be displayed as.</summary>
76+
<value>The rate at which this metric should be displayed.</value>
77+
<remarks>
78+
<format type="text/markdown"><![CDATA[
79+
## Remarks
80+
81+
The value of the `DisplayRateTimeScale` property is included as a string in the payload.
82+
83+
]]></format>
84+
</remarks>
7685
</Docs>
7786
</Member>
7887
<Member MemberName="ToString">

‎xml/System.Diagnostics.Tracing/PollingCounter.xml

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,15 @@
1818
<remarks>
1919
<format type="text/markdown"><![CDATA[
2020
21-
`PollingCounter` differs from <see cref="T:System.Diagnostics.Tracing.EventCounter" /> in that it takes a callback function to collect metrics on its own rather than requiring the user to call <see cref="M:System.Diagnostics.Tracing.EventCounter.WriteMetric(System.Double)" /> every time.
21+
## Remarks
22+
23+
<xref:System.Diagnostics.Tracing.PollingCounter> is a variant of <xref:System.Diagnostics.Tracing.EventCounter> that uses a callback method to poll for values rather than requiring the writer to explicitly call <xref:System.Diagnostics.Tracing.EventCounter.WriteMetric%2A?displayProperty=nameWithType> each time a value is tracked, `metricProvider` is a callback method that polls for values. The <xref:System.Diagnostics.Tracing.PollingCounter> instance polls and reports a value retrieved by calling `metricProvider` exactly once per the interval requested by the listener.
24+
25+
A <xref:System.Diagnostics.Tracing.PollingCounter> lives as long as the <xref:System.Diagnostics.Tracing.EventSource> that it is attached to unless it is explicitly disposed.
26+
27+
`PollingCounter` differs from <xref:System.Diagnostics.Tracing.EventCounter> in that it takes a callback function to collect metrics on its own rather than requiring the user to call <xref:System.Diagnostics.Tracing.EventCounter.WriteMetric%2A> every time.
28+
29+
For an example that uses <xref:System.Diagnostics.Tracing.PollingCounter> 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.
2230
2331
]]></format>
2432
</remarks>
@@ -43,15 +51,9 @@
4351
<Docs>
4452
<param name="name">The name for this <see cref="T:System.Diagnostics.Tracing.PollingCounter" /> instance.</param>
4553
<param name="eventSource">The event source.</param>
46-
<param name="metricProvider">To be added.</param>
54+
<param name="metricProvider">A method that will be used to poll the value.</param>
4755
<summary>Initializes a new instance of the <see cref="T:System.Diagnostics.Tracing.PollingCounter" /> class.</summary>
48-
<remarks>
49-
<format type="text/markdown"><![CDATA[
50-
51-
Polling counters live as long as the <see cref="T:System.Diagnostics.Tracing.EventSource" /> that they are attached to unless they are explicitly disposed.
52-
53-
]]></format>
54-
</remarks>
56+
<remarks>To be added.</remarks>
5557
</Docs>
5658
</Member>
5759
<Member MemberName="ToString">
@@ -77,4 +79,4 @@ Polling counters live as long as the <see cref="T:System.Diagnostics.Tracing.Eve
7779
</Docs>
7880
</Member>
7981
</Members>
80-
</Type>
82+
</Type>

‎xml/System.Diagnostics/Activity.xml

Lines changed: 26 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -19,16 +19,18 @@
1919
<Docs>
2020
<summary>Represents an operation with context to be used for logging.</summary>
2121
<remarks>
22-
<format type="text/markdown"><![CDATA[
22+
<format type="text/markdown"><![CDATA[
23+
24+
## Remarks
2325
2426
An `Activity` has an operation name, an ID, a start time and duration, tags, and baggage.
25-
27+
2628
The current activity can be accessed with the static <xref:System.Diagnostics.Activity.Current?displayProperty=nameWithType> property.
2729
2830
Activities should be created by calling the constructor, configured as necessary, and then started with the <xref:System.Diagnostics.Activity.Start%2A> method, which maintains parent-child relationships for the activities and sets <xref:System.Diagnostics.Activity.Current?displayProperty=nameWithType>.
29-
31+
3032
When an activity is finished, it should be stopped with the <xref:System.Diagnostics.Activity.Stop?displayProperty=nameWithType> method.
31-
33+
3234
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).
3335
3436
]]></format>
@@ -114,8 +116,7 @@ Note that <xref:System.Diagnostics.Activity> has a "builder" pattern: you call t
114116
<param name="key">The baggage key.</param>
115117
<param name="value">The baggage value.</param>
116118
<summary>Updates the <see cref="T:System.Diagnostics.Activity" /> to have a new baggage item with the specified key and value.</summary>
117-
<returns>
118-
<see langword="this" /> for convenient chaining.</returns>
119+
<returns><see langword="this" /> for convenient chaining.</returns>
119120
<remarks>
120121
<format type="text/markdown"><![CDATA[
121122
@@ -155,8 +156,7 @@ This key/value pair is included in the collection returned by the <see cref="P:S
155156
<param name="key">The tag key.</param>
156157
<param name="value">The tag value.</param>
157158
<summary>Updates the <see cref="T:System.Diagnostics.Activity" /> to have a new tag with the provided <paramref name="key" /> and <paramref name="value" />. .</summary>
158-
<returns>
159-
<see langword="this" /> for convenient chaining.</returns>
159+
<returns><see langword="this" /> for convenient chaining.</returns>
160160
<remarks>
161161
<format type="text/markdown"><![CDATA[
162162
@@ -581,8 +581,7 @@ The root ID is a substring from the <xref:System.Diagnostics.Activity.Id> or the
581581
<Docs>
582582
<param name="endTimeUtc">The UTC stop time.</param>
583583
<summary>Updates the <see cref="T:System.Diagnostics.Activity" /> to set its <see cref="P:System.Diagnostics.Activity.Duration" /> as the difference between <see cref="P:System.Diagnostics.Activity.StartTimeUtc" /> and the specified stop time.</summary>
584-
<returns>
585-
<see langword="this" /> for convenient chaining.</returns>
584+
<returns><see langword="this" /> for convenient chaining.</returns>
586585
<remarks>To be added.</remarks>
587586
</Docs>
588587
</Member>
@@ -635,8 +634,7 @@ The root ID is a substring from the <xref:System.Diagnostics.Activity.Id> or the
635634
<Docs>
636635
<param name="parentId">The ID of the parent operation.</param>
637636
<summary>Updates this <see cref="T:System.Diagnostics.Activity" /> to indicate that the <see cref="T:System.Diagnostics.Activity" /> with an ID of <paramref name="parentId" /> caused this <see cref="T:System.Diagnostics.Activity" />.</summary>
638-
<returns>
639-
<see langword="this" /> for convenient chaining.</returns>
637+
<returns><see langword="this" /> for convenient chaining.</returns>
640638
<remarks>
641639
<format type="text/markdown"><![CDATA[
642640
@@ -667,12 +665,20 @@ This property should only be used in 'boundary' scenarios where an <see cref="T:
667665
<Parameter Name="activityTraceFlags" Type="System.Diagnostics.ActivityTraceFlags" Index="2" FrameworkAlternate="netcore-3.0" />
668666
</Parameters>
669667
<Docs>
670-
<param name="traceId">To be added.</param>
671-
<param name="spanId">To be added.</param>
668+
<param name="traceId">The parent activity's TraceId.</param>
669+
<param name="spanId">The parent activity's SpanId.</param>
672670
<param name="activityTraceFlags">To be added.</param>
673-
<summary>To be added.</summary>
674-
<returns>To be added.</returns>
675-
<remarks>To be added.</remarks>
671+
<summary>Sets the parent ID using the W3C convention of a TraceId and a SpanId.</summary>
672+
<returns><see langword="this" /> for convenient chaining.</returns>
673+
<remarks>
674+
<format type="text/markdown"><![CDATA[
675+
676+
## Remarks
677+
678+
This method has the advantage that no string manipulation is needed to set the ID.
679+
680+
]]></format>
681+
</remarks>
676682
</Docs>
677683
</Member>
678684
<Member MemberName="SetStartTime">
@@ -699,8 +705,7 @@ This property should only be used in 'boundary' scenarios where an <see cref="T:
699705
<Docs>
700706
<param name="startTimeUtc">The <see cref="T:System.Diagnostics.Activity" /> start time in UTC.</param>
701707
<summary>Sets the start time of this <see cref="T:System.Diagnostics.Activity" />.</summary>
702-
<returns>
703-
<see langword="this" /> for convenient chaining.</returns>
708+
<returns><see langword="this" /> for convenient chaining.</returns>
704709
<remarks>To be added.</remarks>
705710
</Docs>
706711
</Member>
@@ -746,8 +751,7 @@ This property should only be used in 'boundary' scenarios where an <see cref="T:
746751
<Parameters />
747752
<Docs>
748753
<summary>Starts the activity.</summary>
749-
<returns>
750-
<see langword="this" /> for convenient chaining.</returns>
754+
<returns><see langword="this" /> for convenient chaining.</returns>
751755
<remarks>
752756
<format type="text/markdown"><![CDATA[
753757
@@ -910,4 +914,4 @@ Logically `TraceStateString` is just a kind of baggage (if flows just like bagga
910914
</Docs>
911915
</Member>
912916
</Members>
913-
</Type>
917+
</Type>

0 commit comments

Comments
 (0)