Dev/suwhang/system.diagnostics

xml/System.Diagnostics.Tracing/DiagnosticCounter.xml

@@ -65,9 +65,18 @@
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Gets or sets display name of the counter.</summary>
+        <value>The display name of the counter.</value>
+        <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+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.
+
+   ]]></format>
+
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="DisplayUnits">
@@ -137,8 +146,8 @@ 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>
-        <value>To be added.</value>
+        <summary>Gets the EventSource that this counter is attached to.</summary>
+        <value>The EventSource that this counter is attached to.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -158,8 +167,8 @@ 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>
-        <value>To be added.</value>
+        <summary>Gets the name of this counter.</summary>
+        <value>The name of this counter.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/System.Diagnostics.Tracing/EventCounter.xml

@@ -34,10 +34,11 @@
   <Docs>
     <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  
+      <format type="text/markdown"><![CDATA[
 
-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.
+## Remarks
+
+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).
 
    ]]></format>
     </remarks>
@@ -158,9 +159,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 [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).
+
+       ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="WriteMetric">

xml/System.Diagnostics.Tracing/IncrementingEventCounter.xml

@@ -18,7 +18,11 @@
     <remarks>
       <format type="text/markdown"><![CDATA[  
 
-`IncrementingEventCounter` does not calculate statistics like mean or standard deviation because it only accumulates the counter value.
+## Remarks
+
+`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>
@@ -46,7 +50,9 @@
         <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.
+## Remarks
+
+<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.
 
          ]]></format>
         </remarks>
@@ -68,9 +74,17 @@ 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>Gets or sets the rate at which this metric should be displayed as.</summary>
+        <value>Gets or sets the rate at which this metric should be displayed</value>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+The value of the `DisplayRateTimeScale` property is included as a string in the payload.
+
+         ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Increment">

xml/System.Diagnostics.Tracing/IncrementingPollingCounter.xml

@@ -17,8 +17,16 @@
     <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>
     <remarks>
       <format type="text/markdown"><![CDATA[  
-
-`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.
+
+## Remarks
+
+<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.
+
+`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 <xref:System.Diagnostics.Tracing.IncrementingEventCounter>, this takes in a polling callback that it can call to update  its own metric periodically.
+
+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.
 
     ]]></format>
     </remarks>
@@ -42,16 +50,10 @@
       </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 event source 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.
-
-        ]]></format>
-        </remarks>
+        <remarks>To be added.</remarks>
       </Docs>
     </Member>
     <Member MemberName="DisplayRateTimeScale">
@@ -70,9 +72,16 @@
         <ReturnType>System.TimeSpan</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Gets or sets rate at which this metric should be displayed as.</summary>
+        <value>The rate at which this metric should be displayed.</value>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+## Remarks
+
+The value of the `DisplayRateTimeScale` property is included as a string in the payload.
+
+         ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="ToString">

xml/System.Diagnostics.Tracing/PollingCounter.xml

@@ -18,7 +18,15 @@
     <remarks>
       <format type="text/markdown"><![CDATA[  
 
-`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.
+## Remarks
+
+<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. 
+
+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.
+
+`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.
+
+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.
 
       ]]></format>
     </remarks>
@@ -43,15 +51,9 @@
       <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[  
-
-Polling counters live as long as the <see cref="T:System.Diagnostics.Tracing.EventSource" /> that they are attached to unless they are explicitly disposed.
-
-        ]]></format>
-        </remarks>
+        <remarks>To be added.</remarks>
       </Docs>
     </Member>
     <Member MemberName="ToString">
@@ -77,4 +79,4 @@ Polling counters live as long as the <see cref="T:System.Diagnostics.Tracing.Eve
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.Diagnostics/Activity.xml

@@ -19,16 +19,18 @@
   <Docs>
     <summary>Represents an operation with context to be used for logging.</summary>
     <remarks>
-      <format type="text/markdown"><![CDATA[  
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
 
 An `Activity` has an operation name, an ID, a start time and duration, tags, and baggage.
-             
+
 The current activity can be accessed with the static <xref:System.Diagnostics.Activity.Current?displayProperty=nameWithType> property.
 
 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>.
-            
+
 When an activity is finished, it should be stopped with the <xref:System.Diagnostics.Activity.Stop?displayProperty=nameWithType> 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).
 
          ]]></format>
@@ -114,8 +116,7 @@ Note that <xref:System.Diagnostics.Activity> has a "builder" pattern: you call t
         <param name="key">The baggage key.</param>
         <param name="value">The baggage value.</param>
         <summary>Updates the <see cref="T:System.Diagnostics.Activity" /> to have a new baggage item with the specified key and value.</summary>
-        <returns>
-          <see langword="this" /> for convenient chaining.</returns>
+        <returns><see langword="this" /> for convenient chaining.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
 
@@ -155,8 +156,7 @@ This key/value pair is included in the collection returned by the <see cref="P:S
         <param name="key">The tag key.</param>
         <param name="value">The tag value.</param>
         <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>
-        <returns>
-          <see langword="this" /> for convenient chaining.</returns>
+        <returns><see langword="this" /> for convenient chaining.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -581,8 +581,7 @@ The root ID is a substring from the <xref:System.Diagnostics.Activity.Id> or the
       <Docs>
         <param name="endTimeUtc">The UTC stop time.</param>
         <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>
-        <returns>
-          <see langword="this" /> for convenient chaining.</returns>
+        <returns><see langword="this" /> for convenient chaining.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -635,8 +634,7 @@ The root ID is a substring from the <xref:System.Diagnostics.Activity.Id> or the
       <Docs>
         <param name="parentId">The ID of the parent operation.</param>
         <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>
-        <returns>
-          <see langword="this" /> for convenient chaining.</returns>
+        <returns><see langword="this" /> for convenient chaining.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
 
@@ -667,12 +665,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 TraceId.</param>
+        <param name="spanId">The parent activity's SpanId.</param>
         <param name="activityTraceFlags">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <summary>Sets the parent ID using the W3C convention of a TraceId and a SpanId.</summary>
+        <returns><see langword="this" /> for convenient chaining.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+This method has the advantage that no string manipulation is needed to set the ID.
+
+        ]]></format>
+        </remarks> 
       </Docs>
     </Member>
     <Member MemberName="SetStartTime">
@@ -699,8 +705,7 @@ This property should only be used in 'boundary' scenarios where an <see cref="T:
       <Docs>
         <param name="startTimeUtc">The <see cref="T:System.Diagnostics.Activity" /> start time in UTC.</param>
         <summary>Sets the start time of this <see cref="T:System.Diagnostics.Activity" />.</summary>
-        <returns>
-          <see langword="this" /> for convenient chaining.</returns>
+        <returns><see langword="this" /> for convenient chaining.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -746,8 +751,7 @@ This property should only be used in 'boundary' scenarios where an <see cref="T:
       <Parameters />
       <Docs>
         <summary>Starts the activity.</summary>
-        <returns>
-          <see langword="this" /> for convenient chaining.</returns>
+        <returns><see langword="this" /> for convenient chaining.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
 
@@ -910,4 +914,4 @@ Logically `TraceStateString` is just a kind of baggage (if flows just like bagga
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>