Repository: dotnet/diagnostics

Issue #515: Add docs to better describe the .NET diagnostic experience
Created: 2019-10-01T07:31:32Z
We've done lots of diagnostic work, but customers either aren't aware of it or don't know how it works. We need documentation on docs.microsoft.com to explain everything we've been building in a consistent and accessible way. Now that we have a landing page we need to fill it out much more. If the check list below is too much work for a single work item or hard to parcel out feel free to create additional items that track just one bullet and link them:


Conceptual docs

 Logging and Tracing

 EventListener (it is mentioned but not described). Include init behavior.
 Explain Activity IDs #1347
 #3029


 Symbol and Source Indexing
 Diagnostic Port and Microsoft.Diagnostics.NetCore.Client



Walkthroughs

 Diagnosing CPU usage with dotnet-trace and VS (there is an existing example but it uses PerfView which is harder for many customers to work with)
 #2902
 #2903
 #2904
 #2905
 #2907
 #2908
 #2909
 #2910
 #2911
 Guidance for library writers on creating an EventSource that is easily consumable. This includes adding EventCounters and what types of events are helpful for users. (based on conversation from dotnet/runtime#45247)



EventSource-specific gaps: #1736

  Increased detail on use cases of and differences between the various ctors on EventSource
  Increased documentation on features such as custom keywords
  Clarification on differences between consumption channels, i.e., nuget package, BCL, redist nuget package
 Describe internal mappings of CLR types to eventing payload types, e.g., bool --> int of 0 or 1, DateTime --> FILETIME, etc. (per #2608)



Reference

 Known caveats to tools when used in prod environments. #1737
 Add documentation to Diagnostic Client API



Additional Work

 Dotnet-gcdump collect causes OutOfMemoryException documentation  #2038
 Correctly Document UNMANAGED_CODE_TIME vs CPU_TIME #1166
 Retire duplicate documentation - #1682

Duplicate issue #346: EventCounter vs PerformanceCounter documentation & guidance
Created: 2019-06-18T09:54:39Z
On .Net Full Framework, a PerformanceCounter value seems to survive as long as one producer or one listener exists. Should all producers & listeners of the PerformanceCounter crash, restart, node restarts etc, the value is lost. Does EventCounter running on the .Net Core run-time behave in the same manner?


Official guidance states that PerformanceCounters should not be created & immediately used due to latency time to enable the counters, is the same true for EventCounter running on the .Net Core run-time?


What is the envisaged pattern to re-load an EventCounter on server restart (in light of previous question on delay of usage after creation)?


Lastly any guidance on limits & resource utilization for how many EventCounter counters can be monitored per host on Windows / Linux, for example:
4.1 Can we collect/report on 1000 individual EventCounter counters every 10 seconds. What is the size (1 GB / day) compared to PerformanceCounter?
4.2  Impact on host / container CPU and memory whilst monitoring 1000 individual EventCounter counters every 10 seconds etc?

Closing comment (2019-11-06T06:56:20Z): Going to close this issue because the doc work is being tracked by #515 and this issue was primarily about answering questions. If there is anything I missed just let me know we can reopen/open a new issue as appropriate.