home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 594b.lha / Spy_v0.32 / spy.doc < prev    next >
Text File  |  1992-01-02  |  11KB  |  266 lines
  1.  
  2.               SPY Process Time Monitoring System
  3.               ==================================
  4.  
  5.               By Supervisor Software, 1989,90,91
  6.  
  7.  
  8.  
  9. The SPY system allows one to monitor the overall CPU usage and the CPU times
  10. consumed by various tasks and processes running on the Amiga.
  11.  
  12. These new program version are NOT compatible with the older ones.  Using both
  13. version simultaneously may cause a machine crash.
  14.  
  15. This package consists of three different programs:
  16.  
  17.  * Spy 0.32    - a monitoring program which links itself into the task
  18.           switching vectors of Exec library and maintains its own
  19.           structures for task information storage
  20.  * DSD 1.20    - a graphic display of CPU load with some numeric information
  21.           about Amiga uptime and CPU load
  22.  * Report 1.25    - a CLI utility for listing all tasks and processes in the
  23.           system and showing their CPU usage information
  24.  
  25.  
  26. This package is primarly designed for the new Kickstart and Workbench 2.x
  27. but it will also run on Kickstart 1.3, although the CPU time measurement
  28. is very inaccurate under 1.3 in this version of Spy.  This will be addressed
  29. in the next release of SPY System.
  30.  
  31. Use 'command ?' for a template, 'command ??' for human readable help or
  32. 'command ???' for full online help.
  33.  
  34.  
  35. USAGE:
  36. ======
  37.  
  38. Spy
  39. ~~~
  40. First run Spy to create the new structures and start accounting the CPU
  41. usage and other information.  Spy will return immediately, thus no RUN
  42. instruction is required.  If you wish, you can later remove Spy from the
  43. Amiga by running it again (or running it again with the command Remove,
  44. if desired).  Spy can only be terminated when no DSD or Report programs
  45. are running.
  46.  
  47. Spy has one option (-Times) which causes all tasks and processes started
  48. _before_ Spy to receive Spy's starting time as theirs.  That is, all
  49. processes started before Spy will look like they were started at the same
  50. time with Spy.  If this option is NOT used, the processes mentioned will
  51. have an 'unknown' starting time.
  52.  
  53. All tasks and processes started _after_ Spy was run will always get the
  54. real starting time in their structures.
  55.  
  56.  
  57. DSD
  58. ~~~
  59. You may start DSD right after running Spy.  The initial x and y coordinates
  60. for the DSD window can be specified on the command line.  For example,
  61. DSD -x400 -y0 sets the coordinates to (400,0).  Specifying coordinates of -1
  62. will open the window as far right and down as possible.
  63.  
  64. DSD may be terminated at any moment by clicking its close gadget or sending
  65. a CTRL+C signal to it.
  66.  
  67. The DSD display shows the CPU usage (load) in graphical form.  When the
  68. graph is low, the CPU load is low.  When the CPU is fully loaded, the graph
  69. will fill the entire display.  The graph is updated once a second, thus the
  70. approximate timing of load peaks can also be determined.
  71.  
  72. The Load numbers show the CPU loading.  100% means the CPU is fully loaded.
  73. The number on the left hand side shows the value for the last seconds, the
  74. other shows the CPU load calculated for the total Uptime.
  75.  
  76. IdleCPU shows the total amount of time that CPU has been idle (ie. it has
  77. had nothing to do) and Uptime shows the time that the SPY system has been
  78. running (usually Spy is started during machine boot so this will show the
  79. total uptime of the Amiga).
  80.  
  81.  
  82. Report
  83. ~~~~~~
  84. Report is a CLI based utility used to list all tasks and processes running
  85. on the Amiga.  It shows many kinds of information about the tasks:
  86.  
  87. * First, it lists the Uptime, IdleCPU and Average Load:
  88.  
  89. Uptime:  0 00:23:15.140    Idle CPU:  0 00:21:04.494    Average Load:   9.39%
  90.  
  91. * Then, it lists all tasks and processes in alphabetical order:
  92.  
  93. num taskname (args)        typ  id  pri task ptr stack  used  disp   CPU time
  94.   1 AmiCron                 bw   4    0 078C1C68  8192   314   204      0.339
  95.   2 bin/keylock             bw   2    0 078AFAF8  8192   118     0      0.000
  96.   3 CD0                     pw       10 0788C648  6000   182  2306      0.781
  97.   4 CON                     pw        5 07901C18  3200   530     0      0.000
  98.   5 CON                     pw        5 0790B220  3200   530     0      0.000
  99.   6 CON                     pw        5 078DCE70  3200   530     0      0.000
  100.   7 CON                     pw        5 07871C50  3200   530    16      0.059
  101.   8 console.device          tw        5 0780E160  4096    90    68      0.460
  102.   9 CON                     pw        5 078E5E48  3200   530   544      6.959
  103.  10 DF0                     pw       10 07815B40  2400   130     0      0.000
  104.  11 DF2                     pw       10 078352A0  2400   130     0      0.000
  105.  12 DH0                     pw       10 07817FC0  2400   130   577      0.160
  106.  13 DH1                     pw       10 078379C0  2400   130   800      0.340
  107.  14 DH2                     pw       10 0783D708  2400   130    54      0.000
  108.  15 dsd                     bw   5    0 078E30C8  8192   152  1196      8.062
  109.  16 Enhancer v1.577         pw       10 07883988  8192    94    61      0.000
  110.  17 H0                      pw       10 078230C0  2400   130    10      0.000
  111.  18 H1                      pw       10 07829150  2400   130     0      0.000
  112.  19 H2                      pw       10 0782F1F0  2400   130     0      0.000
  113.  .. ..                      ..       .. ........  ....   ...     .      .....
  114.  .. ..                      ..       .. ........  ....   ...     .      .....
  115.  .. ..                      ..       .. ........  ....   ...     .      .....
  116.  
  117.  
  118. If Spy is not active, the timing information for tasks and processes is not
  119. available.  In that case, the appropriate fields of output will be blank.
  120.  
  121.  
  122. The meanings of the colunms are:
  123.  
  124. num        Line number of printout (may be disabled with option
  125.         -NONumbers)
  126.  
  127. taskname    Name of task or process shown.  Under Workbench 2.0, the
  128.         command line arguments of CLI commands are also shown.
  129.  
  130. typ        Task or process type: First letter indicates if this is a CLI
  131.         background process (b), a process (p) or a simple task (t).
  132.         Second letter shows if this task or process is doing nothing
  133.         (waiting, w) or currently running (ready, r).
  134.  
  135. id        CLI identifier number.
  136.  
  137. pri        Priority (-128...+127) of this task or process.
  138.  
  139. task ptr    Task structure pointer of this task or process.
  140.  
  141. stack        Stack size for this task or process.
  142.  
  143. used        This many bytes of stack are in use.
  144.  
  145. disp        Number of dispatches for this task or process (shows how many
  146.         times this task has been scheduled to run or how many times
  147.         it has needed CPU time).
  148.  
  149. CPU time    CPU time used by this task or process, shown in seconds and
  150.         milliseconds (or seconds only when the value exceeds 1000000
  151.         seconds).  This field is not reliable under 1.3 for the
  152.         current version of Spy.
  153.  
  154. created        (Not shown above) Time when this task or process was started.
  155.         This may be unknown for the tasks that were launched before
  156.         Spy was started (unless -times option is used for Spy).
  157.  
  158. idle        (Not shown above) Time which the task or process has been
  159.         sleeping, needing no CPU time.  If a CLI window or an
  160.         application program is not used, it usually needs no CPU time
  161.         and the idle time is seen here.  Most system processes need
  162.         CPU time several times a second and this field is blank
  163.         (meaning no idle time for that process).
  164.  
  165.  
  166. Report has several command line options:
  167.  
  168. [<pattern>|$<address>|#<cli_id>] [-Time] [-Format="<fmtchars>"]
  169. [-Header[="<header>"]] [-NOHeader] [-[NO]Status] [-[NO]Numbers]
  170. [-CLI] [-Proc] [-TAsk] [-Waiting] [-Ready]
  171.  
  172. The characters shown in UPPER CASE are obligatory, while those in lower
  173. case are optional.  Option strings are case-insensitive.  Thus, -H, -He,
  174. -HEA and -HeAdEr mean all the same option.
  175.  
  176. When <pattern> is specified, Report only lists tasks and processes whose
  177. names match the given pattern string.  Under Workbench 2.x, the standard
  178. AmigaDOS wildcards can be used.  Under 1.3, if the pattern string ends with
  179. an asterisk (*) all task and process names beginning with the given
  180. string will be listed.
  181.  
  182. When $<address> is specified, Report will only list one task with the
  183. Task structure pointer of <address>.  The address mus be given in
  184. hexadecimal as shown in the task ptr field of Report output.  If a given
  185. task is not found, No match will be printed instead of the task's data.
  186.  
  187. When #<cli_id> is specified, Report will only list one CLI process
  188. with the given CLI id number.  The id must be a decimal number.  If a given
  189. process is not found, No match will be printed.
  190.  
  191. -Time option selects the alternate output format of Report, showing the
  192. task starting and idle times instead of some other information.
  193.  
  194. -Format option can be used to specify a custom output format.  The <fmtchars>
  195. may contain nay combination of the following formatting characters:
  196.  
  197.  %n    task name and arguments (shorter format, 22 columns)
  198.  %N    task name and arguments (longer format, 30 columns)
  199.  %t    task or process type
  200.  %c    CLI process id
  201.  %p    priority
  202.  %a    address of Task structure
  203.  %s    stack size and usage
  204.  %d    number of dispatches
  205.  %T    CPU time consumed, long format
  206.  %H    CPU time consumed, short format (hh:mm)
  207.  %C    creation time of task or process
  208.  %i    idle tile of task or process
  209.  
  210. The default format string is "%n %t %c %p %a %s %d %T" and the -Time format
  211. is "%n %t %c %a   %d %T %C %i".
  212.  
  213. -Header enables the header line for printing.  If -Header="<header>" is
  214. specified, the custom header line will be used instead of the standard
  215. one.  The header line can be set in the environment variable (see below).
  216. -NOHeader and -Header control the printing of header.  By default, the
  217. header line is printed unless only one task or process is listed.  For
  218. every -NOHeader, one -Header must be given to reverse the option's effect.
  219.  
  220. -NONumbers and -Numbers control the printing of line numbers.  By default,
  221. the numbers are printed unless only one task or process is listed.  For
  222. every -NONumbers, one -Numbers must be given to reverse the option's effect.
  223.  
  224. -NOStatus and -Status control the printing of status line.  By default, the
  225. status line is printed unless only one task or process is listed.  For
  226. every -NOStatus, one -Status must be given to reverse the option's effect.
  227.  
  228. -CLI causes only CLI processes to be printed.
  229. -TAsk causes only tasks to be printed.
  230. -Proc causes only non-CLI processes to be printed.
  231. If several flags are specified, all task types will be printed.  By default,
  232. all types of tasks and processes are printed.
  233.  
  234. -Ready filters all waiting (idle) processes off the printing causing only
  235. ready processes to be printed.  -Waiting only prints processes which are
  236. sleeping at the moment.  These flags are mutually exclusive.  By default,
  237. all tasks and processes are printed recardless of their state.  These flags
  238. can not be set in the environment variable.
  239.  
  240.  
  241. Options for the Report command can be given in an environment variable
  242. called 'report'.  The command line options can be used to override the
  243. defaults or the ones set by the environment variable when needed.
  244.  
  245.  
  246.  
  247. Other
  248. ~~~~~
  249. These programs are still under development.  Feel free to send bug reports
  250. or suggestions to the author.
  251.  
  252. Thank you for your interest.
  253.  
  254. Supervisor Software
  255.  
  256.  
  257.  
  258. Mail:                     E-Mail:                   Voice:
  259.  
  260.   Jukka Marin               jmarin@uku.fi             int. + 358 71 232 793
  261.   Metsurintie 17 B 8        jmarin@messi.uku.fi
  262.   70150 Kuopio
  263.   FINLAND
  264.  
  265.  
  266.