Merge pull request #12 from newbrough/feature/odds-n-ends

Feature/odds n ends

bin/inspector

@@ -25,38 +25,60 @@ fi
 period=300000 # 5min
 
 ## add args for probes
-opts="-Xmx1g"
-needhook=false
+needagent=false
+needprobe=false
 while [ $# -gt 0 ]
 do
   case "$1" in
-    ## by default, probe is not enabled unless there is some other "main" to trace
-    ## using this option, investigator can monitor stats on itself (demo purposes?)
-    -force)
-      opts="$opts -Dgumshoe.probe.enabled=true "
-      ;;
     -cpu)
-      opts="$opts -Dgumshoe.cpu-usage.period=$period "
-      opts="$opts -Dgumshoe.cpu-usage.sample=5000"
-      opts="$opts -Dgumshoe.cpu-usage.filter.none=true"
+      gumshoe_opts="$gumshoe_opts -Dgumshoe.cpu-usage.period=$period "
+      gumshoe_opts="$gumshoe_opts -Dgumshoe.cpu-usage.sample=5000"
+      gumshoe_opts="$gumshoe_opts -Dgumshoe.cpu-usage.filter.none=true"
+      needprobe=true
       ;;
     -file-io)
-      opts="$opts -Dgumshoe.file-io.period=$period"
-      opts="$opts -Dgumshoe.file-io.filter.none=true"
-      needhook=true
+      gumshoe_opts="$gumshoe_opts -Dgumshoe.file-io.period=$period"
+      gumshoe_opts="$gumshoe_opts -Dgumshoe.file-io.filter.none=true"
+      needagent=true
+      needprobe=true
       ;;
     -socket-io)
-      opts="$opts -Dgumshoe.socket-io.period=$period"
-      opts="$opts -Dgumshoe.socket-io.filter.none=true"
-      needhook=true
+      gumshoe_opts="$gumshoe_opts -Dgumshoe.socket-io.period=$period"
+      gumshoe_opts="$gumshoe_opts -Dgumshoe.socket-io.filter.none=true"
+      needagent=true
+      needprobe=true
       ;;
     -datagram-io)
-      opts="$opts -Dgumshoe.datagram-io.period=$period"
-      opts="$opts -Dgumshoe.datagram-io.filter.none=true"
+      gumshoe_opts="$gumshoe_opts -Dgumshoe.datagram-io.period=$period"
+      gumshoe_opts="$gumshoe_opts -Dgumshoe.datagram-io.filter.none=true"
+      needprobe=true
       ;;
     -unclosed)
-      opts="$opts -Dgumshoe.socket-unclosed.period=$period"
-      opts="$opts -Dgumshoe.socket-unclosed.filter.none=true"
+      gumshoe_opts="$gumshoe_opts -Dgumshoe.socket-unclosed.period=$period"
+      gumshoe_opts="$gumshoe_opts -Dgumshoe.socket-unclosed.filter.none=true"
+      needprobe=true
+      ;;
+    -help)
+      cat << HELPTEXT
+Inspector for gumshoe
+
+Usage: $0 [options...] [target-java-main [target-java-args...]]
+
+Options:
+    -help         Print this message
+    -cpu          Install cpu probe
+    -file-io      Install file I/O probe
+    -socket-io    Install file I/O probe
+    -datagram-io  Install datagram I/O probe
+    -unclosed     Install unclosed socket probe
+
+Any other options are passed to the JRE.
+
+HELPTEXT
+      exit
+      ;;
+    -*)
+      user_opts="$user_opts $1"
       ;;
     *)
       break
@@ -66,28 +88,47 @@ do
   shift
 done
 
-if $needhook
+# by default inspector doesn't usually watch itself,
+# so probes are only installed if there is a target.
+# override if probe was requested...
+if $needprobe && [ $# -eq 0 ]
 then
-  hookdir="$GUMSHOE_HOME/gumshoe-hooks/target"
-  hookcount="`ls $hookdir | grep -c '^gumshoe-hooks-*.jar'`"
-  case $hookcount in
-    0)
-      echo ERROR: gumshoe hook jar not found in $hookdir 1>&2
-      exit 1
-      ;;     
-    1)
-      ## file and socket I/O probes need the sun.misc.SocketIo hook
-      hookfile="`ls $hookdir | grep '^gumshoe-hooks-*.jar'`"
-      opts="$opts -Xbootclasspath/p:$hookdir/$hookfile"
-      ;;     
-    *)
-      ## could get fancy here, but i don't expect people to leave stray jars around
-      echo 'ERROR: more than one gumshoe hook jar found $hookdir !' 1>&2
-      echo 'Rebuild with: mvn clean install' 1>&2
-      exit 1
-      ;;     
-  esac
+  gumshoe_opts="$gumshoe_opts -Dgumshoe.probe.enabled=true "
 fi
 
+if $needagent
+then
+  agent="$GUMSHOE_HOME/gumshoe-probes/target/gumshoe-agent.jar"
+  if [ ! -f "$agent" ]
+  then
+    echo ERROR: did not find gumshoe agent $agent 1>&2
+    exit 1
+  fi
+
+  gumshoe_opts="$gumshoe_opts -javaagent:$agent"
+fi
+
+## now check if any user options override
+
+# if user did not specify max heap, set default
+opts="$user_opts"
+echo " $user_opts" | grep -- ' -Xms' > /dev/null
+if [ $? -ne 0 ]
+then
+     opts="-Xms1g $user_opts"
+fi
+
+# for each property, if user did not specify add ours
+for prop in $gumshoe_opts
+do
+  regex=" `echo $prop | cut -d= -f1`="
+  echo " $user_opts" | grep -- "$regex" > /dev/null
+  if [ $? -ne 0 ]
+  then
+    opts="$opts $prop"
+  fi
+done
+
 ## warning: can fail if orig cmdline contains quoted expressions like: java some.MainClass "first arg" second "third arg"
+echo EXECUTING: java $opts -jar "$jarfile" $*
 java $opts -jar "$jarfile" $*

docs/filters.md

@@ -10,7 +10,7 @@ frames to identify exactly what is relevant to your application and the current
 As a side note, there are really two places where stack frames are filtered.  In the probe, a loose filter
 can drop the most obvious candidates to reduce the memory usage and file size while collecting data.
 Then in the viewer a more restrictive filter can better refine the view.  To start, maybe just exclude
-the JDK and gumshoe classes in the probe (the default).  After collecting and looking at samples from
+the JDK and gumshoe classes in the probe (the default).  After collecting and looking at reports from
 your application, you will better be able to identify other packages and classes to exclude from collection.
 
 I'll describe ONE APPROACH I've used to get good results from gumshoe.  I'm sure this isn't the only way

docs/index.md

@@ -24,20 +24,20 @@ Getting Started
 - Step by step
 
 
-Collecting Samples
+Generating Reports
 ------------------
 
 - [About the hooks](hooks.md)
 - [Configuring the probe](probe.md)
 - [Using filters](filters.md)
 - [Running your program](run.md)
 
-Viewing Samples
+Viewing Reports
 ---------------
 
 - Running gumshoe GUI from your JVM
 - Running standalone GUI
-- Selecting a data sample
+- Selecting a data report
 - Navigating the graph
 - Graph display options
 - Configuring filters

docs/probe/event-handling.md

@@ -51,8 +51,6 @@ to improve reporting.
     gumshoe.datagram-io.handler.queue-size=1000    
     gumshoe.file-io.handler.queue-size=1000    
 
-
-
   The queue will fill if events are produced (individual I/O operations) faster than they are consumed.
   Some possible reasons:
 
@@ -73,28 +71,5 @@ to improve reporting.
     Or it could be due to gumshoe stack filters.  Each stack filter configured has to
     modify the event call stack on the same event handling thread.  Complex filters
     (such as the recursion filter) or deep call stacks can result in more load than the
-    thread can handle.  Relax [filters](../filters.md) (at the expense of more memory use) or increase the
-    event handler thread priority.      
-
-  If the event queue is full:
-
-  - Ignore it (_really!, it isn't so bad..._)
-
-    If the problem is intermittent, it may not affect all samples, 
-    and data reported in those affected is still likely a representative subset of all I/O.
-    Total I/O values will not be accurate but the relative I/O comparisons between threads
-    should still provide insight into what the target application is doing to generate the I/O load.
-
-  - Increase queue size
-
-    If the problem is intermittent, then a larger queue can let the handler thread
-    catch up after load spikes.  However, if load is consistently over the handler capacity,
-    this will just delay and not fix the problem.  (Requires restart)
-
-  - Increase handler thread priority
-
-    Socket and file I/O events perform all filtering and accumulation functions on the
-    handler thread.  The default is to run at Thread.MIN_PRIORITY, reflecting the decision to
-    risk dropping data rather than impact the target application.  This can be changed to a
-    higher value to reduce dropping events even if it means taking some CPU time away from
-    the target application.
+    thread can handle.  Relax [filters](../filters.md) (at the expense of more memory use) 
+    or increase the number of threads or the event handler thread priority.

docs/probe/jmx-cpu-stats.md

@@ -20,8 +20,8 @@ This mbean will allow you to alter these attributes:
 In addition these operations can be performed:
 
     getReport()             Return a text report of the current contents of the collection buffer.
-                            This will likely represent a partial sample if periodic reporting is enabled
+                            This will likely represent a partial report if periodic reporting is enabled
                             for the time since the start of the last reporting interval.
     reset()                 Clear the contents of the collection buffer.
                             If periodic reporting is enabled, the next report sent to configured listeners
-                            will not contain a full sample as this data will have been removed.
+                            will not contain a full report as this data will have been removed.

docs/probe/jmx-file-io.md

@@ -14,8 +14,8 @@ This mbean will allow you to alter these attributes:
 In addition these operations can be performed:
 
     getReport()             Return a text report of the current contents of the collection buffer.
-                            This will likely represent a partial sample if periodic reporting is enabled
+                            This will likely represent a partial report if periodic reporting is enabled
                             for the time since the start of the last reporting interval.
     reset()                 Clear the contents of the collection buffer.
                             If periodic reporting is enabled, the next report sent to configured listeners
-                            will not contain a full sample as this data will have been removed.
+                            will not contain a full report as this data will have been removed.

docs/probe/jmx-socket-io.md

@@ -14,8 +14,8 @@ This mbean will allow you to alter these attributes:
 In addition these operations can be performed:
 
     getReport()             Return a text report of the current contents of the collection buffer.
-                            This will likely represent a partial sample if periodic reporting is enabled
+                            This will likely represent a partial report if periodic reporting is enabled
                             for the time since the start of the last reporting interval.
     reset()                 Clear the contents of the collection buffer.
                             If periodic reporting is enabled, the next report sent to configured listeners
-                            will not contain a full sample as this data will have been removed.
+                            will not contain a full report as this data will have been removed.

docs/probe/properties-cpu-stats.md

@@ -8,8 +8,8 @@ Configuration Properties
 
 Initialization can use system properties by calling Probe.initialize() or with an explicit Properties argument.
 
-    gumshoe.cpu-usage.period     Data samples will be reported at regular intervals (in milliseconds)
-    gumshoe.cpu-usage.onshutdown If true, data samples will be reported when the JVM exits
+    gumshoe.cpu-usage.period     Reports will be generated at regular intervals (in milliseconds)
+    gumshoe.cpu-usage.onshutdown If true, a report will be generated when the JVM exits
     gumshoe.cpu-usage.mbean      If true, enable JMX control of CPU usage probe
     gumshoe.cpu-usage.mbean.name Override name of JMX control
                                  (default is based on fully qualified class name) 
@@ -18,6 +18,7 @@ Initialization can use system properties by calling Probe.initialize() or with a
                                  now but enable/disable the reporting at another time.
     gumshoe.cpu-usage.priority   Thread priority for data collection thread (default value is Thread.MIN_PRIORITY)
     gumshoe.cpu-usage.sample            Thread data collection rate (milliseconds, default 5000)
+                                        Generally multiple samples are accumulated into each report.
     gumshoe.cpu-usage.jitter            Collection rate should vary randomly by this 
                                         amount (milliseconds, default 0)
     gumshoe.cpu-usage.use-wait-times    Thread contention monitoring is enabled by default on
@@ -29,9 +30,9 @@ Stacks should generally be [filtered](../filters.md) reduce overhead and simplif
 
     gumshoe.cpu-usage.filter...    See common filter properties [here](filter-properties.md) 
 
-Collected data samples are written to:
+Collected data reports are written to:
 
-    gumshoe.cpu-usage.output=none   Do not write samples (ie, when your program is
-                                    adding its own explicit Listener to receive samples)
+    gumshoe.cpu-usage.output=none   Do not write reports (ie, when your program is
+                                    adding its own explicit Listener to receive reports)
     gumshoe.cpu-usage.output=stdout Write to System.out (the default)
     gumshoe.cpu-usage.output=file:/some/path    Write to a text file.

docs/probe/properties-datagram-io.md

@@ -8,8 +8,8 @@ Configuration Properties
 
 Initialization can use system properties by calling Probe.initialize() or with an explicit Properties argument.
 
-    gumshoe.datagram-io.period     Data samples will be reported at regular intervals (in milliseconds)
-    gumshoe.datagram-io.onshutdown If true, data samples will be reported when the JVM exits
+    gumshoe.datagram-io.period     Data reports will be generated at regular intervals (in milliseconds)
+    gumshoe.datagram-io.onshutdown If true, a report will be generated when the JVM exits
     gumshoe.datagram-io.mbean      If true, enable JMX control of datagram usage probe
     gumshoe.datagram-io.mbean.name Override name of JMX control
                                  (default is based on fully qualified class name) 
@@ -35,10 +35,10 @@ Stacks should generally be [filtered](../filters.md) reduce overhead and simplif
 
     gumshoe.datagram-io.filter...    See common filter properties [here](filter-properties.md) 
 
-Collected data samples are written to:
+Collected data reports are written to:
 
-    gumshoe.datagram-io.output=none   Do not write samples (ie, when your program is
-                                    adding its own explicit Listener to receive samples)
+    gumshoe.datagram-io.output=none   Do not write reports (ie, when your program is
+                                    adding its own explicit Listener to receive reports)
     gumshoe.datagram-io.output=stdout Write to System.out (the default)
     gumshoe.datagram-io.output=file:/some/path    Write to a text file.
 

docs/probe/properties-file-io.md

@@ -8,8 +8,8 @@ Configuration Properties
 
 Initialization can use system properties by calling Probe.initialize() or with an explicit Properties argument.
 
-    gumshoe.file-io.period     Data samples will be reported at regular intervals (in milliseconds)
-    gumshoe.file-io.onshutdown If true, data samples will be reported when the JVM exits
+    gumshoe.file-io.period     Data reports will be reported at regular intervals (in milliseconds)
+    gumshoe.file-io.onshutdown If true, data reports will be reported when the JVM exits
     gumshoe.file-io.mbean      If true, enable JMX control of file usage probe
     gumshoe.file-io.mbean.name Override name of JMX control
                                (default is based on fully qualified class name) 
@@ -35,9 +35,9 @@ Stacks should generally be [filtered](../filters.md) reduce overhead and simplif
     gumshoe.file-io.filter...    See common filter properties [here](filter-properties.md) 
 
 
-Collected data samples are written to:
+Collected data reports are written to:
 
-    gumshoe.file-io.output=none   Do not write samples (ie, when your program is
-                                    adding its own explicit Listener to receive samples)
+    gumshoe.file-io.output=none   Do not write reports (ie, when your program is
+                                    adding its own explicit Listener to receive reports)
     gumshoe.file-io.output=stdout Write to System.out (the default)
     gumshoe.file-io.output=file:/some/path    Write to a text file.

docs/probe/properties-socket-io.md

@@ -8,8 +8,8 @@ Configuration Properties
 
 Initialization can use system properties by calling Probe.initialize() or with an explicit Properties argument.
 
-    gumshoe.socket-io.period     Data samples will be reported at regular intervals (in milliseconds)
-    gumshoe.socket-io.onshutdown If true, data samples will be reported when the JVM exits
+    gumshoe.socket-io.period     Data reports will be generated at regular intervals (in milliseconds)
+    gumshoe.socket-io.onshutdown If true, a report will be generated when the JVM exits
     gumshoe.socket-io.mbean      If true, enable JMX control of socket usage probe
     gumshoe.socket-io.mbean.name Override name of JMX control
                                  (default is based on fully qualified class name) 
@@ -35,9 +35,9 @@ Stacks should generally be [filtered](../filters.md) reduce overhead and simplif
 
     gumshoe.socket-io.filter...    See common filter properties [here](filter-properties.md) 
 
-Collected data samples are written to:
+Collected data reports are written to:
 
-    gumshoe.socket-io.output=none   Do not write samples (ie, when your program is
-                                    adding its own explicit Listener to receive samples)
+    gumshoe.socket-io.output=none   Do not write reports (ie, when your program is
+                                    adding its own explicit Listener to receive reports)
     gumshoe.socket-io.output=stdout Write to System.out (the default)
     gumshoe.socket-io.output=file:/some/path    Write to a text file.

docs/probe/properties-unclosed-socket.md

@@ -9,8 +9,8 @@ Configuration Properties
 
 Initialization can use system properties by calling Probe.initialize() or with an explicit Properties argument.
 
-    gumshoe.socket-unclosed.period     Data samples will be reported at regular intervals (in milliseconds)
-    gumshoe.socket-unclosed.onshutdown If true, data samples will be reported when the JVM exits
+    gumshoe.socket-unclosed.period     Reports will be generated at regular intervals (in milliseconds)
+    gumshoe.socket-unclosed.onshutdown If true, a report will be generated when the JVM exits
     gumshoe.socket-unclosed.mbean      If true, enable JMX control of socket usage probe
     gumshoe.socket-unclosed.mbean.name Override name of JMX control
                                        (default is based on fully qualified class name) 
@@ -22,9 +22,9 @@ Stacks should generally be [filtered](../filters.md) reduce overhead and simplif
 
     gumshoe.socket-unclosed.filter...    See common filter properties [here](filter-properties.md) 
 
-Collected data samples are written to:
+Collected data reports are written to:
 
-    gumshoe.socket-unclosed.output=none   Do not write samples (ie, when your program is
-                                          adding its own explicit Listener to receive samples)
+    gumshoe.socket-unclosed.output=none   Do not write reports (ie, when your program is
+                                          adding its own explicit Listener to receive reports)
     gumshoe.socket-unclosed.output=stdout Write to System.out (the default)
     gumshoe.socket-unclosed.output=file:/some/path    Write to a text file.