From: Sung Yoon Whang Date: Wed, 1 May 2019 23:07:10 +0000 (-0700) Subject: Dotnet counters doc (#219) X-Git-Tag: submit/tizen/20190813.035844~6^2^2~48 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=fba7e0a03d15a9410c29a7d8594f644bfdf4c821;p=platform%2Fcore%2Fdotnet%2Fdiagnostics.git Dotnet counters doc (#219) * some documentation updates to dotnet-counters * Readme under dotnet-counters directory * some cleanup * Adding example for filtering' * fix list cmd * Adding some more description in example usage per PR feedback * PR feedback * Give some example counters to intro section * Some syntax fix * Add dotnet-counters doc to main README --- diff --git a/README.md b/README.md index 30a100763..3868df912 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,7 @@ Getting a version of lldb that works for your platform can be a problem sometime * [dotnet-dump](documentation/dotnet-dump-instructions.md) - Dump collection and analysis utility. * [dotnet-trace](documentation/dotnet-trace-instructions.md) - Enable the collection of events for a running .NET Core Application to a local trace file. +* [dotnet-counters](src/Tools/dotnet-counters/README.md) - Monitor performance counters of a .NET Core application in real time. ## New Features diff --git a/documentation/design-docs/dotnet-tools.md b/documentation/design-docs/dotnet-tools.md index d65101f5d..a8a9b8df3 100644 --- a/documentation/design-docs/dotnet-tools.md +++ b/documentation/design-docs/dotnet-tools.md @@ -11,26 +11,18 @@ These are some quick examples of the work we'd expect a .Net developer to want t > dotnet tool install -g dotnet-counters You can invoke the tool using the following command: dotnet-counters Tool 'dotnet-counters' (version '1.0.0') was successfully installed. - > dotnet counters monitor --process-id 1902 System.Runtime Microsoft.AspNet - + > dotnet-counters monitor --process-id 1902 --refresh-interval 1 System.Runtime + + Press p to pause, r to resume, q to quit. System.Runtime: - Total Processor Time (ms) 173923.48 - Private Virtual Memory (MB) 1094 + CPU Usage (%) 24 Working Set (MB) 1982 - Virtual Memory (MB) 3041 - GC Heap Memory (MB) 784 - Exception Thrown Rate (exceptions/min) 117 - Lock Contention Rate (contentions/min) 1792 - - Microsoft.AspNet: - Request Rate (requests/sec) 1915 - Request Latency (ms) 34 + GC Heap Size (MB) 811 + Gen 0 GC / second 20 + Gen 1 GC / second 4 + Gen 1 GC / Second 1 + Number of Exceptions / sec 4 - 'p' - pause updates - 'r' - resume updates - 'q' - quit - -(Counter groups are for example purpose only, exact groups/counters TBD) ### Capture a trace for performance analysis @@ -167,8 +159,8 @@ LIST Examples: > dotnet-counters list - Showing well-known counters only. Specific processes may support additional counters. + Showing well-known counters only. Specific processes may support additional counters. System.Runtime total-processor-time Amount of time the process has utilized the CPU (ms) private-memory Amount of private virtual memory used by the process (KB) @@ -176,18 +168,45 @@ LIST virtual-memory Amount of virtual memory used by the process (KB) gc-total-memory Amount of committed virtual memory used by the GC (KB) exceptions-thrown-rate Number of exceptions thrown in a recent 1 minute window (exceptions/min) - lock-contention-rate Number of instances of lock contention on runtime implemented locks in a - recent 1 minute window (contentions/min) - Microsoft.AspNet - request-rate Number of requests handled in a recent one second interval (requests/sec) - request-latency Time to respond to a request, averaged over all requests in a recent - one second interval (ms) MONITOR + Examples: + + 1. Monitoring all counters from `System.Runtime` at a refresh interval of 3 seconds: + + > dotnet-counters monitor --process-id 1902 --refresh-interval 3 System.Runtime + Press p to pause, r to resume, q to quit. + System.Runtime: + CPU Usage (%) 24 + Working Set (MB) 1982 + GC Heap Size (MB) 811 + Gen 0 GC / second 20 + Gen 1 GC / second 4 + Gen 1 GC / Second 1 + Number of Exceptions / sec 4 + + + 2. Monitoring just CPU usage and GC heap size from `System.Runtime` at a refresh interval of 5 seconds: + + > dotnet-counters monitor --process-id 1902 --refresh-interval 5 System.Runtime[cpu-usage,gc-heap-size] + Press p to pause, r to resume, q to quit. + System.Runtime: + CPU Usage (%) 24 + GC Heap Size (MB) 811 + + 3. Monitoring EventCounter values from user-defined EventSource: (see https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md on how to do this.0) + + > dotnet-counters monitor --processId 1902 Samples-EventCounterDemos-Minimal + + Press p to pause, r to resume, q to quit. + request 100 + + Syntax: + dotnet-counters monitor [-h||--help] [-p|--process-id ] - [--refreshInterval ] + [--refresh-interval ] counter_list Display periodically refreshing values of selected counters @@ -207,25 +226,7 @@ MONITOR provider and counter names, use the list command. - Examples: - > dotnet counters monitor --processId 1902 System.Runtime Microsoft.AspNet - System.Runtime: - Total Processor Time (ms) 173923.48 - Private Virtual Memory (MB) 1094 - Working Set (MB) 1982 - Virtual Memory (MB) 3041 - GC Heap Memory (MB) 784 - Exception Thrown Rate (exceptions/min) 117 - Lock Contention Rate (contentions/min) 1792 - - Microsoft.AspNet: - Request Rate (requests/sec) 1915 - Request Latency (ms) 34 - - 'p' - pause updates - 'r' - resume updates - 'q' - quit ### dotnet-trace @@ -386,7 +387,7 @@ Examples: Writing minidump to file ./core_20190226_135837 Written 98983936 bytes (24166 pages) to core file Complete - + $ dotnet dump collect --process-id 1902 --type mini Writing minidump to file ./core_20190226_135850 Written 98959360 bytes (24160 pages) to core file @@ -458,12 +459,12 @@ The following commands are supported: histobjfind Displays all the log entries that reference an object at the specified address. histroot Displays information related to both promotions and relocations of the specified root. setsymbolserver Enables the symbol server support. - ``` +``` The "modules", "threads" and "setthread" commands display/control the native state. In addition new commands are listed below: - + GCHEAPDIFF gcheapdiff diff --git a/src/Tools/dotnet-counters/README.md b/src/Tools/dotnet-counters/README.md new file mode 100644 index 000000000..d7900f266 --- /dev/null +++ b/src/Tools/dotnet-counters/README.md @@ -0,0 +1,117 @@ +# dotnet-counters + + +## Intro + +dotnet-counters is a performance monitoring tool for ad-hoc health monitoring or 1st level performance investigation. It can observe performance counter values that are published via `EventCounter` API (https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.tracing.eventcounter). For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application to see if there is anything suspiscious before diving into more serious performance investigation using PerfView or dotnet-trace. + + +## Install dotnet-counters + +``` +dotnet tool install --global dotnet-counters --version 1.0.3-preview5.19228.1 --add-source https://dotnetfeed.blob.core.windows.net/dotnet-core/index.json +``` + + +## Using dotnet-counters + +*SYNOPSIS* + + dotnet-counters [--version] + [-h, --help] + [] + +*OPTIONS* + + --version + Display the version of the dotnet-counters utility. + + -h, --help + Show command line help + +*COMMANDS* + + list Display a list of counter names and descriptions + monitor Display periodically refreshing values of selected counters + +*LIST* + + dotnet-counters list [-h|--help] + + Display a list of counter names and descriptions, grouped by provider. + + -h, --help + Show command line help + + Examples: + > dotnet-counters list + + Showing well-known counters only. Specific processes may support additional counters. + System.Runtime + cpu-usage Amount of time the process has utilized the CPU (ms) + working-set Amount of working set used by the process (MB) + gc-heap-size Total heap size reported by the GC (MB) + gen-0-gc-count Number of Gen 0 GCs / sec + gen-1-gc-count Number of Gen 1 GCs / sec + gen-2-gc-count Number of Gen 2 GCs / sec + exception-count Number of Exceptions / sec + +*MONITOR* + + ### Examples: + + 1. Monitoring all counters from `System.Runtime` at a refresh interval of 3 seconds: + + > dotnet-counters monitor --processId 1902 System.Runtime + + Press p to pause, r to resume, q to quit. + System.Runtime: + CPU Usage (%) 24 + Working Set (MB) 1982 + GC Heap Size (MB) 811 + Gen 0 GC / second 20 + Gen 1 GC / second 4 + Gen 1 GC / Second 1 + Number of Exceptions / sec 4 + + 2. Monitoring just CPU usage and GC heap size from `System.Runtime` at a refresh interval of 5 seconds: + + > dotnet-counters monitor --processId 1902 System.Runtime[cpu-usage,gc-heap-size,exception-count] + + Press p to pause, r to resume, q to quit. + System.Runtime: + CPU Usage (%) 24 + GC Heap Size (MB) 811 + Number of Exceptions / sec 4 + + 3. Monitoring EventCounter values from user-defined EventSource: (see https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md on how to do this.0) + + > dotnet-counters monitor --processId 1902 Samples-EventCounterDemos-Minimal + + Press p to pause, r to resume, q to quit. + request 100 + + + ### Syntax: + + dotnet-counters monitor [-h||--help] + [-p|--process-id ] + [--refreshInterval ] + counter_list + + Display periodically refreshing values of selected counters + + -h, --help + Show command line help + + -p,--process-id + The ID of the process that will be monitored + + --refresh-interval + The number of seconds to delay between updating the displayed counters + + counter_list + A space separated list of counters. Counters can be specified provider_name[:counter_name]. If the + provider_name is used without a qualifying counter_name then all counters will be shown. To discover + provider and counter names, use the list command. +