
monitor threads utility user guide
version 0.4

2020-10-13 SHL

== Introduction ==

  The purpose of monitorthreads is to help identify which threads are
  consuming excessive CPU resources so that the issue can be remediated.

  There are a number of tools that monitor CPU activity at the process level
  and there are some tools, such as sid2, that can report CPU utilization at
  the thread level.  Monitorthreads.exe implements the ability to monitor
  per thread CPU utilization over time.

  Monitorthreads calculates the system time and user time used by each thread
  during a collection interval and lists these values for the busiest
  threads.

== Usage ==

  Monitorthreads is a VIO command line application.  Output is written to
  the standard output and can be redirected to a file or piped into another
  applications for post-processing.

  To display the help screen, enter

     monitorthreads.exe -?

  at the command line.  The help screen will display as:

  Monitor thread activity and report busy threads. v0.3.

  monitorthreads [-c cutoff] [-d] [-h] [-i sec] [-l limit] [-u] [-V] [-w] [-?]

    -c cutoff Ignore threads using fewer ticks than cutoff.  Default is 5.
    -d        Enable debug mode.
    -h -?     Display this message.
    -i secs   Set collection interval in seconds.  Default is 1 sec.
    -l limit  Limit number of threads reported.  Default is 5.
    -u        Count user time.  Default counts all time.
    -V        Display version.
    -s        Count system time.
    -w        Watch for busy threads.  This is the default action.

  Copyright (c) 2014-2020 Steven Levine and Associates, Inc.
  All rights reserved.

  Cutoff can be used to filter out threads with lower CPU usage.  The default
  cutoff of 5 counts represents about 150 milliseconds of CPU time.

  The cutoff interval can be increased from the default 1 second.  This will
  have the effect of reporting threads that are busier for longer periods of
  time.

  The limit value can be used to show fewer or more of the busiest threads
  per collection interval.  The default is 5 threads however if the system
  is not busy fewer than 5 threads might be selected for display.

  The default is to sum the system time and user time for filtering and
  reporting.  The -u and -s options allow the calculations to be limited to
  user time or system time only.

  If both -u and -s are specified the sum of the system time and the user
  time are used for filtering and both times are reported separately.

  To run monitorthreads with default options, enter

     monitorthreads.exe

  at the command line.  When run with no options, monitorthread will report
  up to 5 threads that accumulate more than 5 counts of system and user time
  with a collection interval of 1 second.

  Typical output is

  2014-05-06 13:10:53 CPE.EXE            PID 3755 TID 1 651.0 msec ready
  2014-05-06 13:10:55 MONITORTHREADS.EXE PID 3825 TID 1 31.0 msec running

  To terminate monitorthreads use Ctrl-C or Ctrl-Break.

== Theory of operation ==

  Monitorthreads uses the DosQuerySysState API to collect per thread data.
  This data includes the total system and user time accumulated by the
  thread along with the thread's execution state.

  The kernel accumulates system or user time for the current thread
  while processing the system timer interrupt.  This limits the accuracy of
  the accumulated times.  The kernel increments the system time or user time
  accumulator depending on the current thread's privilege level.  These
  numbers are useful but not the same as actual execution time.  A thread may
  not have run for the entire timer interrupt interval.  The thread or
  threads that ran during the rest of the interval will not accumulate
  any time.

  The are additional issues with calculating the system time used by a thread
  during the collection interval. The current thread may be in system mode
  and may be blocked.  The kernel will accumulate system time for this thread
  even though it is not really running.

  Monitorthreads implements heuristics that attempt to detect if the
  calculated system time is for a blocked thread and will force the value 0
  zero when this is the case.  However, monitor threads has no way of knowing
  if the thread was blocked for the entire collection interval.

== Known Issues ==

  System time reporting still feels like it accumulates more than it should.

  If system is busy, collection interval can be longer than setting.

  DosQuerySysState is a bit buggy and can report bogus data at times.  If
  monitorthreads traps, please report the traps so that workarounds can be
  implemented.

== eof ==
