home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 3 / Meeting_Pearls_III.iso / Pearls / debug / Monitor / SpySystem / SpySystem.doc < prev    next >
Text File  |  1995-06-25  |  19KB  |  491 lines
  1.  
  2.               SPY Process Time Monitoring System
  3.               ==================================
  4.  
  5.              By Supervisor Software 1989,90,91,92
  6.  
  7.  
  8.                       Revision 3.0
  9.  
  10.  
  11.  
  12.  
  13. The SPY system allows one to monitor the overall CPU usage and the CPU
  14. times consumed by various tasks and processes running on the Amiga.
  15.  
  16. These new program versions are NOT compatible with the older ones.  Using
  17. different versions simultaneously may cause a system crash.
  18.  
  19.  
  20. This package consists of three different programs:
  21.  
  22. Spy v3.02    - This program loads and initializes a shared library which
  23.           contains the time monitoring routines and a few other
  24.           routines called by the tools included.  This program must
  25.           be run before any other tools can be used.
  26.  
  27. DSD v3.00    - A graphic display of CPU loading with numeric information
  28.           about the system uptime and CPU load.
  29.  
  30. Report v3.00    - A CLI utility for listing all tasks and processes in the
  31.           system and showing their CPU usage information.
  32.  
  33. TopCPU v3.02    - A new addition to Spy system.  This program currently
  34.           lists ten most CPU intensive tasks or processes and their
  35.           relative CPU usage.
  36.  
  37. CPUTime v0.50    - A new addition to Spy system.  This program measures the
  38.           CPU time and real time consumed by any CLI program.  This
  39.           program is currently in it's beta testing phase.
  40.  
  41. sssystem.library v5.3
  42.         - This is a shared library which must be present for the
  43.           other tools to work.  This library must be initialized by
  44.           the Spy program before any timing measurements are done.
  45.           This is because it would otherwise be impossible to pass
  46.           any options to the library.
  47.  
  48.  
  49.  
  50. This package is primarly designed for the new Kickstart and Workbench 2.x,
  51. but it will also run on Kickstart 1.3, although the CPU time measurement is
  52. very inaccurate under 1.3 unless a CIA hardware timer is used (see below).
  53.  
  54. Use 'command ?' for a template, 'command ??' for human readable help or
  55. 'command ???' for full online help in any of the programs mentioned above.
  56.  
  57. Spy, DSD, and TopCPU may also be launched wrom Workbench (new in Release 3).
  58.  
  59.  
  60.  
  61. USAGE:
  62. ======
  63.  
  64. Spy
  65. ~~~
  66. First run Spy to load and initialize sssystem.library.  Spy will return
  67. immediately, thus no RUN command is required.  If you wish, you can later
  68. later remove Spy from the Amiga by running it again with the Remove option.
  69. Spy can only be removed from the system when no DSD/TOPCpu/CPUTime/Report
  70. programs are running.
  71.  
  72. Spy has a few command line options to control the operation of the time
  73. monitoring system.
  74.  
  75.  Install        installs Spy routines in memory (initializes the library)
  76.  Remove         removes Spy routines from memory (deintializes the library)
  77.  Times          sets Started time to current time for all tasks
  78.  Atimer         uses CIAB timer A for timing
  79.  Btimer         uses CIAB timer B for timing
  80.  
  81. You must always specify either Install or Remove (only the upper case
  82. characters of any option are needed, so you can use I for Install and R
  83. fo Remove).
  84.  
  85. The option Times causes all tasks and processes started _before_ Spy to
  86. receive the current time as their starting time.  That is, all processes
  87. started before Spy will look like they were started at the same time with
  88. Spy.  If this option is NOT used, the processes mentioned will have an
  89. 'unknown' starting time.
  90. All tasks and processes started _after_ Spy was run will always get the
  91. real starting time in their structures.
  92.  
  93. Options A and B are used to allocate a CIA B hardware timer for accurate
  94. time keeping.  If neither is used, sssystem.library will use the time in
  95. Dos library's RootNode (under Workbench 1.x) or the system ReadEClock()
  96. routine (under Workbench 2.x).
  97. It is recommended to use either A or B, especially under Workbench 1.x,
  98. where there is no good way of reading an accurate time from the system.
  99. An inaccurate time may cause serious timing problems with DSD, Report, and
  100. TOPCpu.
  101. Under Workbench 2.04, the accuracy of ReadEClock() is the same as that of
  102. the sssystem.library's own CIA timer routines.  However, the routines of
  103. the sssystem.library are more optimized and result in slightly better
  104. overall performance.  If both CIA B timers are needed by other programs,
  105. the options can be left out and the system's ReadEClock() used instead.
  106.  
  107. SpySystem can now be installed from Workbench using tool type "INSTALL".
  108. Timers may be specified with "ATIMER" or "BTIMER", starting times may
  109. be set with "TIMES" and removal of SpySystem is done with "REMOVE".
  110. If Spy is started via a project icon, the tool types of that icon are
  111. used for the program options.
  112.  
  113.  
  114.  
  115. DSD
  116. ~~~
  117. You may start DSD right after running Spy.  The initial x and y coordinates
  118. for the DSD window can be specified on the command line.  For example,
  119. DSD x400 y0 sets the coordinates to (400,0).  Specifying coordinates of -1
  120. will open the window as far right and down as possible.
  121.  
  122. Normally DSD updates its display once a second.  The user can specify a
  123. different interval time (1...3600 seconds) using the Interval option:
  124.  
  125. DSD I60
  126.  
  127. sets the interval to 60 seconds.
  128.  
  129. DSD may be terminated at any moment by clicking its close gadget or sending
  130. a CTRL+C signal to it.
  131.  
  132. The DSD display shows the CPU usage (load) in graphical form.  When the
  133. graph is low, the CPU load is low.  When the CPU is fully loaded, the graph
  134. will fill the entire display.  The graph is updated once every <interval>
  135. seconds, thus the approximate timing of load peaks can also be determined.
  136.  
  137. The Load numbers show the CPU loading.  100% means the CPU is fully loaded.
  138. The number on the left hand side shows the value for the last seconds, the
  139. other shows the CPU load calculated for the total Uptime.
  140.  
  141. IdleCPU shows the total amount of time that CPU has been idle (ie. it has
  142. had nothing to do) and Uptime shows the time that the SPY system has been
  143. running (usually Spy is started during machine boot so this will show the
  144. total uptime of the Amiga).
  145.  
  146.  
  147.  
  148. Report
  149. ~~~~~~
  150. Report is a CLI based utility used to list all tasks and processes running
  151. on the Amiga.  It shows many kinds of information about the tasks:
  152.  
  153. FIRST, it lists the Uptime, IdleCPU and Average Load:
  154.  
  155. Uptime:  0 00:23:15.140    Idle CPU:  0 00:21:04.494    Average Load:   9.39%
  156.  
  157. THEN, it lists all tasks and processes in alphabetical order:
  158.  
  159. num taskname (args)        typ  id  pri task ptr stack  used  disp   CPU time
  160.   1 AmiCron                 bw   4    0 078C1C68  8192   314   204      0.339
  161.   2 bin/keylock             bw   2    0 078AFAF8  8192   118     0      0.000
  162.   3 CD0                     pw       10 0788C648  6000   182  2306      0.781
  163.   4 CON                     pw        5 07901C18  3200   530     0      0.000
  164.   5 CON                     pw        5 0790B220  3200   530     0      0.000
  165.   6 CON                     pw        5 078DCE70  3200   530     0      0.000
  166.   7 CON                     pw        5 07871C50  3200   530    16      0.059
  167.   8 console.device          tw        5 0780E160  4096    90    68      0.460
  168.   9 CON                     pw        5 078E5E48  3200   530   544      6.959
  169.  10 DF0                     pw       10 07815B40  2400   130     0      0.000
  170.  11 DF2                     pw       10 078352A0  2400   130     0      0.000
  171.  12 DH0                     pw       10 07817FC0  2400   130   577      0.160
  172.  13 DH1                     pw       10 078379C0  2400   130   800      0.340
  173.  14 DH2                     pw       10 0783D708  2400   130    54      0.000
  174.  15 dsd                     bw   5    0 078E30C8  8192   152  1196      8.062
  175.  16 Enhancer v1.577         pw       10 07883988  8192    94    61      0.000
  176.  17 H0                      pw       10 078230C0  2400   130    10      0.000
  177.  18 H1                      pw       10 07829150  2400   130     0      0.000
  178.  19 H2                      pw       10 0782F1F0  2400   130     0      0.000
  179.  .. ..                      ..       .. ........  ....   ...     .      .....
  180.  .. ..                      ..       .. ........  ....   ...     .      .....
  181.  .. ..                      ..       .. ........  ....   ...     .      .....
  182.  
  183.  
  184. If ssystem.librayry is not active, the timing information for tasks and
  185. processes is not available.  In that case, the appropriate fields of output
  186. will be blank.
  187.  
  188.  
  189. The meanings of the colunms are:
  190.  
  191. num        Line number of printout (may be disabled with option
  192.         -NONumbers)
  193.  
  194. taskname    Name of task or process shown.  Under Workbench 2.0, the
  195.         command line arguments of CLI commands are also shown.
  196.  
  197. typ        Task or process type: First letter indicates if this is a
  198.         CLI background process (b), a process (p) or a simple task
  199.         (t).  Second letter shows if this task or process is doing
  200.         nothing (waiting, w) or currently ready to run (ready, r).
  201.  
  202. id        CLI identifier number.
  203.  
  204. pri        Priority (-128...+127) of this task or process.
  205.  
  206. task ptr    Task structure pointer of this task or process.
  207.  
  208. stack        Stack size for this task or process.
  209.  
  210. used        This many bytes of stack are in use.
  211.  
  212. disp        Number of dispatches for this task or process (shows how
  213.         many times this task has been scheduled to run or how many
  214.         times it has needed CPU time).
  215.  
  216. CPU time    CPU time used by this task or process, shown in seconds and
  217.         milliseconds (or seconds only when the value exceeds 1000000
  218.         seconds).  This field is not reliable under WB 1.3 for the
  219.         current version of Spy without a CIA timer (see below).
  220.  
  221. total CPU    (Not shown above) Total CPU time consumed by the current
  222.         task or process AND all tasks and processes created by it.
  223.         Note that the CPU usage of the child tasks and processes is
  224.         added to total CPU number only when the child or parent dies.
  225.  
  226. created        (Not shown above) Time when this task or process was
  227.         started.  This may be unknown for the tasks that were
  228.         launched before Spy was started (unless -Times option is
  229.         used for Spy).
  230.  
  231. idle        (Not shown above) Time which the task or process has been
  232.         sleeping, needing no CPU time.  If a CLI window or an
  233.         application program is not used, it usually needs no CPU
  234.         time and the idle time is seen here.  Most system processes
  235.         need CPU time several times a second and this field is
  236.         blank (meaning no idle time for that process).
  237.  
  238. sigalloc    (Not shown above) The task signal bits allocated by this
  239.         task or process.
  240.  
  241. sigwaitf    (Not shown above) The signal bits this task or process is
  242.         currently waiting for.
  243.  
  244. sigexcpt    (Not shown above) The signal bits on which this task or
  245.         process will execute an exception routine.
  246.  
  247. sigrecvd    (Not shown above) The signal bits received by the task or
  248.         process.
  249.  
  250. parent        (Not shown above) Task pointer for the process which created
  251.         the current one (empty if unknown or if parent process has
  252.         already died).
  253.  
  254.  
  255. Report has several command line options:
  256.  
  257. [<pattern>|$<address>|#<cli_id>] [-Time] [-Format="<fmtchars>"]
  258. [-Header[="<header>"]] [-NOHeader] [-[NO]Status] [-[NO]Numbers]
  259. [-CLI] [-Proc] [-SIgnals] [-TAsk] [-Waiting] [-Ready] [-Unix]
  260.  
  261. The characters shown in UPPER CASE are obligatory, while those in lower
  262. case are optional.  Option strings are case-insensitive.  Thus, -H, -He,
  263. -HEA and -HeAdEr mean all the same option.
  264.  
  265. When <pattern> is specified, Report only lists tasks and processes whose
  266. names match the given pattern string.  Under Workbench 2.x, the standard
  267. AmigaDOS wildcards can be used.  Under 1.3, if the pattern string ends with
  268. an asterisk (*) all task and process names beginning with the given
  269. string will be listed.
  270.  
  271. When $<address> is specified, Report will only list one task with the
  272. Task structure pointer of <address>.  The address mus be given in
  273. hexadecimal as shown in the task ptr field of Report output.  If a given
  274. task is not found, No match will be printed instead of the task's data.
  275.  
  276. When #<cli_id> is specified, Report will only list one CLI process
  277. with the given CLI id number.  The id must be a decimal number.  If a given
  278. process is not found, No match will be printed.
  279.  
  280. -Time option selects the alternate output format of Report, showing the
  281. task starting and idle times instead of some other information.
  282.  
  283. -Format option can be used to specify a custom output format.  <fmtchars>
  284. may contain nay combination of the following formatting characters (cols
  285. lists the number of columns that will be needed in output):
  286.  
  287. chr   cols    explanation
  288.  %n    22    task name and arguments (shorter format, 22 columns)
  289.  %N    30    task name and arguments (longer format, 30 columns)
  290.  %t     3    task or process type
  291.  %c     3    CLI process id
  292.  %p     4    priority
  293.  %a     8    address of Task structure
  294.  %s    11    stack size and usage
  295.  %d     5    number of dispatches
  296.  %T    10    CPU time consumed, long format
  297.  %H     5    CPU time consumed, short format (hh:mm)
  298.  %C     7    creation time of task or process
  299.  %i     6    idle tile of task or process
  300.  %S    36    task signal bits
  301.  %h    10    total CPU time including children which have died
  302.  %P     8    parent process Task pointer
  303.  
  304. The default format string is "%n %t %c %p %a %s %d %T" and the -Time format
  305. is "%n %t  %a %T %h %C %i".
  306.  
  307. -Header enables the header line for printing.  If -Header="<header>" is
  308. specified, the custom header line will be used instead of the standard
  309. one.  The header line can be set in the environment variable (see below).
  310. -NOHeader and -Header control the printing of header.  By default, the
  311. header line is printed unless only one task or process is listed.  For
  312. every -NOHeader, one -Header must be given to reverse the option's effect.
  313.  
  314. -NONumbers and -Numbers control the printing of line numbers.  By default,
  315. the numbers are printed unless only one task or process is listed.  For
  316. every -NONumbers, one -Numbers must be given to reverse the option's effect.
  317.  
  318. -NOStatus and -Status control the printing of status line.  By default, the
  319. status line is printed unless only one task or process is listed.  For
  320. every -NOStatus, one -Status must be given to reverse the option's effect.
  321.  
  322. -CLI causes only CLI processes to be printed.
  323. -TAsk causes only tasks to be printed.
  324. -Proc causes only non-CLI processes to be printed.
  325. If several flags are specified, all the specified task types will be printed.
  326. By default, all types of tasks and processes are printed.
  327.  
  328. -Ready filters all waiting (idle) processes off the printing causing only
  329. ready processes to be printed.  -Waiting only prints processes which are
  330. sleeping at the moment.  These flags are mutually exclusive.  By default,
  331. all tasks and processes are printed recardless of their state.  These flags
  332. can not be set in the environment variable.
  333.  
  334. -Signals lists the states of task's signal bits (found in the Task structure).
  335.  
  336. -PArent option lists the parent processes if they are known.
  337.  
  338. Options for the Report command can be given in an environment variable
  339. called 'report'.  The command line options can be used to override the
  340. defaults or the ones set by the environment variable when needed.
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349. TopCPU
  350. ~~~~~~
  351. TopCPU has similar options as DSD.  TopCPU shows ten most CPU intensive
  352. tasks or processes and the relative CPU times (percents) in both numeric
  353. and graphical format.
  354.  
  355. You may start TopCPU right after running Spy.  The initial x and y
  356. coordinates for the TopCPU window can be specified on the command line.
  357. For example, TopCPU x0 y200 sets the coordinates to (0,200).  Specifying
  358. coordinates of -1 will open the window as far right and down as possible.
  359.  
  360. Normally TopCPU updates its display every five seconds.  The user can
  361. specify a different interval time (0.1 to 60.9 seconds) using the Interval
  362. option:
  363.  
  364. TopCPU I0.5
  365.  
  366. sets the interval to 0.5 seconds.  Using shorter interval times increases
  367. the CPU load caused by TopCPU due to more frequent display updates.
  368.  
  369. TopCPU may be terminated at any moment by clicking its close gadget or
  370. sending a CTRL+C signal to it.
  371.  
  372. TopCPU lists ten tasks or processes getting most of the CPU time at a
  373. time.  The calculation is done for the whole Interval time; for example,
  374. with the default interval of five seconds, a task which has gotten 60% of
  375. the CPU time has consumed (60/100)*5 seconds or 3 seconds of CPU time.
  376.  
  377. The mincpu option sets the minimum CPU percentage to be displayed.  The
  378. value is given in promilles (0.1 percent):
  379.  
  380. TopCPU M5
  381.  
  382. sets the minimum CPU displayed to 0.5 percent.
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391. CPUTime
  392. ~~~~~~~
  393. CPUTime measures the real and CPU time used by a given CLI command like
  394. a compiler or a sort program.  The only arguments needed by CPUTime are
  395. the command to be run and its arguments.
  396.  
  397. CPUTime CLI-command arguments
  398.  
  399. Only the CPU time used by <CLI-command>'s process is measured.  If the
  400. command outputs text or uses other file-I/O, the CPU time consumed by
  401. the console window processes etc. is NOT taken into account.
  402.  
  403. CPUTime now outputs three values:
  404.  
  405. Fast0: 10> cputime say "Hello world"
  406. Real 00:00:01.448, PCPU 00:00:00.046, TCPU 00:00:00.046
  407.  
  408. The first number shows the real time elapsed in HH:MM:SS.mil format (mil
  409. means milliseconds).  PCPU shows the CPU time consumed by the command
  410. (here by say).  TCPU shows the total CPU time used by the command and
  411. any processes it creates (upto the moment they die or command exits,
  412. whichever happens first).
  413.  
  414. TCPU does NOT include the CPU time used by any process which was not
  415. created by the command.
  416.  
  417. NOTE: CPUTime currently uses Execute() routine to launch the commands.
  418. This may change in the future.  Main processes break signals are now
  419. passed to the child.
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426. NEW FOR RELEASE 3
  427. =================
  428.  
  429. Release 3 of SpySystem now supports the Workbench.  DSD, TopCPU, and Spy
  430. may now be started from Workbench in a normal way.  The following tool
  431. types are recognized:
  432.  
  433. DSD:    xcoord   - sets the window x coordinate (in pixels)
  434.     ycoord   - sets the window y coordinate (in pixels)
  435.     interval - sets the refresh time interval (in seconds)
  436.     CLIicon  - uses the icon settings also when started from CLI
  437.  
  438. TopCPU: xcoord   - sets the window x coordinate (in pixels)
  439.     ycoord   - sets the window y coordinate (in pixels)
  440.     interval - sets the refresh time interval (in seconds)
  441.     CLIicon  - uses the icon settings also when started from CLI
  442.     mincpu   - sets the lowest CPU to be shown (in promilles)
  443.     nonull   - disables the listing for NULL task
  444.  
  445. Spy:    install     - activates the SpySystem
  446.     remove     - deactivates the SpySystem
  447.     times     - sets all tasks' starting times
  448.     atimer     - uses CIAB timer A for time keeping
  449.     btimer     - uses CIAB timer B for time keeping
  450.  
  451. DSD and Report can read the default options from the icon file even when
  452. started from CLI.  To do this, the icon file must be in the same directory
  453. with the executable command file AND the tool type CLIicon must be set for
  454. the icon.  The icon-set defaults can always be overridden on command like.
  455. If CLIicon is NOT used, the icon information will NOT be used when starting
  456. DSD and TopCPU.  The CLIicon tool type has no effect when the program is
  457. started from Workbench.
  458.  
  459.  
  460. The Report command now has new functions.  It keeps track of the child
  461. processes CPU times as well as parent process pointers.  See the
  462. documentation for Report for more information.
  463.  
  464. TopCPU no longer shows the NULL task if CLI option -nonull or WB tool
  465. type NONULL is used.
  466.  
  467.  
  468.  
  469.  
  470.  
  471. Other
  472. =====
  473.  
  474. These programs are still under development.  Feel free to send bug reports
  475. or suggestions to the author.
  476.  
  477. Thank you for your interest.
  478.  
  479. Supervisor Software
  480.  
  481.  
  482.  
  483. Mail:                     E-Mail:                  Voice/FAX:
  484.  
  485.   Jukka Marin               jmarin@messi.uku.fi      int. + 358 71 232 793
  486.   Metsurintie 17 B 8
  487.   70150 Kuopio
  488.   FINLAND
  489.  
  490.  
  491.