Merge pull request #3 from ashrafMahgoub/main

Edit help messages + Documentation

Author: ashrafMahgoub

Documentation/Testing and Validation/StressTesting.docx

@@ -128,20 +128,22 @@ Timestamp,containerID,PID,process,cgroupID,core,cycles,insts,cpi,l1i_mpi,l1d_hit
 
 ### NN\_detect
 ```
-usage: NN_detect.py [-h] [-p PID] [-c CID] -r REF_SIGNATURE [-d DISTANCE_RATIO]
+usage: NN_detect.py [-h] [-p PID] [-c CID] [--outfile OUTFILE] [-s SYSTEM_WIDE_SIGNATURES_PATH | -r REF_SIGNATURE] [-d DISTANCE_RATIO]
 
 Detect Noisy Neighbors for a given PID (process-level) or container ID (container-level).
 
 options:
   -h, --help            show this help message and exit
   -p PID, --pid PID     PID (process-level)
   -c CID, --cid CID     Container ID (container-level)
+  --outfile OUTFILE     Output file to save live-updated performance data
+  -s SYSTEM_WIDE_SIGNATURES_PATH, --system_wide_signatures_path SYSTEM_WIDE_SIGNATURES_PATH
+                        path to signatures_*.csv CSV file with referernce signatures per container ID, as generated by dockermon.
   -r REF_SIGNATURE, --ref_signature REF_SIGNATURE
-                        The tool will use this signature as a baseline. All live updated signatures will be compared to the reference. Use a standalone signature (when the proccess is the
-                        only process executing in the system), or any signature collected over a performance-acceptable duration.
+                        The tool will use this signature as a baseline. Use the output of either procmon or dockermon to collect the signature. The first element in the signature is `cycles`. All live updated signatures will be compared
+                        to this reference signature. Use a standalone signature (when the process is the only process executing in the system), or any signature collected over a performance-acceptable duration.
   -d DISTANCE_RATIO, --distance_ratio DISTANCE_RATIO
-                        Acceptable ratio of change in signature from reference, default is 0.1. If the distance is higher than this value, the monitored workload will flagged as a noisy
-                        neigbor victim.
+                        Acceptable ratio of change in signature from reference, default is 0.1. If the distance is higher than this value, the monitored workload will flagged as a noisy neighbor victim.
 ```
 ### Example output
 ```
@@ -158,6 +160,26 @@ Detected Signature on core 9 :   [3092000000.0, 1403000000.0, 2.2, 0.0, 0.0, 1.0
 Distance from reference: 7.51%   ==> Performance is OK
 ```
 =======
+## Units:
+| Metric           | Unit         |
+| -----------------| -------------|
+| cycles           | RAW          |
+| insts		       | RAW          |
+| cpi              | RAW          |
+| l1i_mpi		   | Percentage   |
+| l1d_hit_ratio    | Percentage   |
+| l1d_miss_ratio   | Percentage   |
+| l2_miss_ratio    | Percentage   |
+| l3_miss_ratio	   | Percentage   |
+| local_bw         | MB/sec       |
+| remote_bw		   | MB/sec       |
+| disk_reads       | MB/sec       |
+| disk_writes	   | MB/sec       |
+| network_tx       | MB/sec       |
+| network_rx	   | MB/sec       |
+| scheduled_count  | RAW	      |
+| avg_q_len		   | RAW          |
+| avg_q_latency    | milliseconds |
 
 ## Notes:
 ** Interference Detector was developed using the following as references:
@@ -167,5 +189,5 @@ Distance from reference: 7.51%   ==> Performance is OK
 4. github.com/iovisor/bcc/blob/master/tools/runqlen.py (Apache 2.0)
 5. github.com/iovisor/bcc/blob/master/tools/runqlat.py (Apache 2.0)
 
-** Interference Detector currently supports "Skylake", "Cascade Lake", "Ice Lake", and "Sapphire Rapids" platforms only. It also supports AWS metal instances where PMUs are availabel (e.g., r5.metal, m5.metal, m6i.metal, etc.).
+** Interference Detector currently supports "Skylake", "Cascade Lake", "Ice Lake", and "Sapphire Rapids" platforms only. It also supports AWS metal instances where PMUs are available (e.g., r5.metal, m5.metal, m6i.metal, etc.). For AWS Single socket instances (r.g., c5.12xlarge, c6i.16xlarge), offcore counters are not available. Hence offcore metrics (e.g., local_bw, remote_bw) will be zeroed out.