rename sample to report

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.

docs/types/datagram-io.md

@@ -8,7 +8,7 @@ For each unique call stack that performs sends or receives a datagram,
 gumshoe reports totals for read, write and combined:
 number of calls, number of bytes, and elapsed time.  
 
-Samples collected can be filtered by IP, mask and port to limit results to only certain systems or services.
+Samples collected can be filtered by IP, mask and port to limit reports to only certain systems or services.
 
 Hooks
 -----
@@ -39,51 +39,5 @@ Limitations
   - While the queue capacity is exceeded, events may be dropped and a message is shown in STDOUT
 
   If this is happening occasionally during peak loads, it may not be an issue.  I/O statistics are still
-  gathered -- it just samples fewer when the queue is full.  If this is happening a lot during the loads
-  being tested then it can be addressed.  
-
-  The queue will fill if events are produced (individual I/O operations) faster than they are consumed.
-  Some possible reasons:
-
-  - The target application is performing a lot of small network operations
-
-    This could be an area to improve the target application.  
-    Lots of small operations are less efficient than fewer large operations.
-
-    Or this could just be the nature of the expected application load,
-    so increase the gumshoe event queue size and the handler thread priority to accommodate. 
-
-  - The JVM is CPU bound
-
-    The event queue may back up if the target application is CPU bound.  This could be
-    an issue in the target application itself, and you may want to look at
-    [processor utilization statistics](../types/cpu-stats.md) before socket I/O.
-
-    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.
+  gathered -- it just samples fewer operations when the queue is full.  If this is happening a lot during the loads
+  being tested then look at then [event handler configuration](../probes/event-handling.md).