Spot precision option

spot-ml/SPARKCONF.md

@@ -1,14 +1,14 @@
-##Spark Configuration
+## Spark Configuration
 
-oni-ml main component uses Spark and Spark SQL to analyze network events and produce a list of least probable events
-or most suspicious. 
+spot-ml main component uses Spark and Spark SQL to analyze network events and those considered the most unlikely
+or most suspicious.
 
-To run oni-ml with its best performance and scalability, it will probably be necessary to configure Yarn, Spark and Spot. Here are our recommended settings.  
+To run spot-ml with its best performance and scalability, it will probably be necessary to configure Yarn, Spark and Spot. Here are our recommended settings.  
 
 ### General Yarn tuning
 
-oni-ml Spark application has been developed and tested on CDH [Yarn](http://spark.apache.org/docs/latest/running-on-yarn.html) 
-clusters. Careful tuning of the Yarn cluster may be necessary before analyzing large amounts of data with oni-ml.
+spot-ml Spark application has been developed and tested on CDH [Yarn](http://spark.apache.org/docs/latest/running-on-yarn.html) 
+clusters. Careful tuning of the Yarn cluster may be necessary before analyzing large amounts of data with spot-ml.
 
 For small data sets, under 100 GB parquet files, default _Yarn_ configurations should be enough
 but if users try to analyze hundreds of gigabytes of data in parquet format it's probable that it don't work; _Yarn_ most likely will start killing
@@ -27,10 +27,10 @@ one try before getting any results.
 
 When running _Spark_ on _Yarn_ users can set up a set of properties in order to get the best performance and consume resources in a more
 effective way. Since not all clusters are the same and not all users are planning to have the same capacity of computation, we have created
-variables that users need to configure before running oni-ml.
+variables that users need to configure before running spot-ml.
 
-After installing oni-setup users will find the [spot.conf](https://github.com/Open-Network-Insight/open-network-insight/blob/spot/spot-setup/spot.conf) 
-file under /etc folder. This file contains all the required configuration to run oni-ml, as explained in [INSTALL.md](https://github.com/Open-Network-Insight/oni-ml/blob/master/INSTALL.md). In this
+After installing spot-setup users will find the [spot.conf](https://github.com/apache/incubator-spot/blob/master/spot-setup/spot.conf) 
+file under /etc folder. This file contains all the required configuration to run spot-ml, as explained in [INSTALL.md](https://github.com/apache/incubator-spot/blob/master/spot-ml/INSTALL.md). In this
 file exist a section for _Spark_ properties, below is the explanation for each of those variables:
 
             SPK_EXEC=''                 ---> Maximumn number of executors
@@ -39,16 +39,18 @@ file exist a section for _Spark_ properties, below is the explanation for each o
             SPK_DRIVER_MAX_RESULTS=''   ---> Maximumn driver results in MB or GB i.e. 8g
             SPK_EXEC_CORES=''           ---> Cores per executor i.e. 4
             SPK_DRIVER_MEM_OVERHEAD=''  ---> Driver memory overhead in MB i.e. 3047. Note that there is no "m" at the end.
-            SPAK_EXEC_MEM_OVERHEAD=''   ---> Executor memory overhead in MB i.e. 3047. Note that there is no "m" at the end.
+            SPK_EXEC_MEM_OVERHEAD=''    ---> Executor memory overhead in MB i.e. 3047. Note that there is no "m" at the end.
+            SPK_AUTO_BRDCST_JOIN_THR='10485760' ---> Spark's spark.sql.autoBroadcastJoinThreshold. Default is 10MB, increase this value to make Spark broadcast tables larger than 10 MB and speed up joins.
+            PRECISION='64'              ---> Indicates whether spot-ml is to use 64 bit floating point numbers or 32 bit floating point numbers when representing certain probability distributions.
 
-Besides the variables in duxbay.conf, users can modify the rest of the properties in ml_ops.sh based on their needs.
+Besides the variables in spot.conf, users can modify the rest of the properties in ml_ops.sh based on their needs.
 
 #### Setting Spark properties
 
- After _Yarn_ cluster has been tuned the next step is to set Spark properties assigning the right values to duxbay.conf _Spark_
+ After _Yarn_ cluster has been tuned the next step is to set Spark properties assigning the right values to spot.conf _Spark_
  variables. 
 
-#####Number of Executors, Executor Memory, Executor Cores and Executor Memory Overhead
+##### Number of Executors, Executor Memory, Executor Cores and Executor Memory Overhead
 
 The first thing users need to know is how to set the number of executors and the memory per executor as well as the number of cores.
 To get that number, users should know the available total memory per node after _Yarn_ tuning, this total memory is determined by _yarn.nodemanager.resource.memory-mb_ 
@@ -87,16 +89,16 @@ Is recommended to keep a close relation between cores and executor memory.
 
 Lastly, for overhead memory we recommend to use something between 8% and 10% of executor memory.
 
-Following the example, the values for the _Spark_ variables in duxbay.conf would look like this:
+Following the example, the values for the _Spark_ variables in spot.conf would look like this:
 
             SPK_EXEC='43'
             SPK_EXEC_MEM='30475m'
             SPK_EXEC_CORES='6'
             SPAK_EXEC_MEM_OVERHEAD='3047'
 
-#####Driver Memory, Driver Maximum Results and Driver Memory Overhead
+##### Driver Memory, Driver Maximum Results and Driver Memory Overhead
 
- oni-ml application executes actions such as _.collect_, _.orderBy_, _.saveAsTextFile_ so we recommend to assign a 
+ spot-ml application executes actions such as _.collect_, _.orderBy_, _.saveAsTextFile_ so we recommend to assign a 
  considerable amount of memory for the driver. 
 
  The same way, driver maximum results should be enough for the serialized results.
@@ -120,34 +122,64 @@ and 50 GB. Driver maximum results should be something equal or bigger than 8 GB.
         SPK_DRIVER_MEM='30475m'
         SPK_DRIVER_MAX_RESULTS='8g'
         SPK_DRIVER_MEM_OVERHEAD='3047'
-
- ![DriverMemory](https://raw.githubusercontent.com/Open-Network-Insight/oni-docs/master/images/Driver%20Memory.png)
+
 
  _Representation of memory allocation in driver node._
 
-
  For more information about Spark properties click [here](http://spark.apache.org/docs/latest/configuration.html).
 
-###Known Spark error messages running oni-ml
+ ##### Spark autoBroadcastJoinThreshold in spot-ml
+
+ After Spark LDA runs, Topics Matrix and Topics Distribution are joined with the original data set  i.e. NetFlow records, DNS records or Proxy records to determine the probability of each event to happen. This joining  process is similar to join a big data set and a lookup table. In this case, the big data set is the entire set of records, and the lookup table is a dictionary of documents and probabilities per topic or words and probabilities per topic. 
+
+ Because of the possible diversity of documents/IPs, the lookup table containing document probability distribution can grow to something bigger than 10 MB. Taking in account that 10 MB is Spark's default auto broadcast threshold for joins, a join with a lookup table bigger than that threshold will result in the execution of a traditional join with lots of shuffling. 
+
+The correct setting of  SPK_AUTO_BRDCST_JOIN_THR and PRECISION can help to always broadcast document probability distribution lookup table and avoid slow joins. 
+
+As a first step, users need to decide whether they want to change from 64 bit floating point probabilities to 32 bit floating point probabilities; if users decide to change from 64 to 32 bit, the document probability distribution lookup table will be half the size and more easily broadcasted. 
+
+If users want to cut payload memory consumption roughly in half, they should set the precision option to 32.
+
+ >PRECISION='32' 
+
+ If users prefer to keep 64 bit floating point numbers, they should set precision option to 64 (default).
+
+ >PRECISION='64'
+
+Given the approximate number of distinct IPs in every batch or data set being analyzed, users should set SPK_AUTO_BRDCST_JOIN_THR to something that can fit the document probability distribution lookup table. 
+
+For instance, if a user knows there can be 2,000,000 distinct IP addresses and is using 20 Topics, the document probability distribution lookup table can grow to something like 190 bytes per row if using PRECISION as 64 bit and 110 bytes per row if using 32 bit option.
+
+> Document probability distribution lookup table record example: 
+
+>(192.169.111.110, [0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05]
+
+In that case, users should set auto broadcast join threshold to something that can fit 365 MB (380000000 Bytes) for 64 bit floating precision numbers or 210 MB (220000000 Bytes) for 32 bit floating precision numbers.
+
+> PRECISION='32'
+
+> SPK_AUTO_BRDCST_JOIN_THR='220000000'
+
+### Known Spark error messages running spot-ml
 
-####Out Of Memory Error
+#### Out Of Memory Error
 
 This issue includes _java.lang.OutOfMemoryError: Java heap space_ and _java.lang.OutOfMemoryError : GC overhead limit exceeded_.
 When users get OOME can be for many different issues but we have identified a couple of reasons for this
-error in oni-ml. 
+error in spot-ml. 
 
-The main reason for this error in oni-ml can be when the ML algorithm returns large results for _word probabilities per topic_.
+The main reason for this error in spot-ml can be when the ML algorithm returns large results for _word probabilities per topic_.
 Since ML algorithm results are broadcast, each executor needs more memory.
 
 Another possible reason for this error is driver is running out of memory, try increasing driver memory.
 
-####Container killed by Yarn for exceeding memory limits. _X.Y_ GB of _X_ GB physical memory used. Consider boosting spark.yarn.executor memoryOverhead
+#### Container killed by Yarn for exceeding memory limits. _X.Y_ GB of _X_ GB physical memory used. Consider boosting spark.yarn.executor memoryOverhead
 
 This issue is caused by certain operations, mainly during the join of _document probabilities per topic_ with the rest of 
 the data - scoring stage. If users receive this error they should try with increasing memory overhead up to 10% of executor memory
 or increase executors memory.
 
-####org.apache.spark.serializer.KryoSerializer 
+#### org.apache.spark.serializer.KryoSerializer 
 
 KryoSerializer can cause issues if property _spark.kryoserializer.buffer.max_ is not enough for the data being serialized.
 Try increasing memory up to 2 GB but keeping in mind the total of the available memory.

spot-ml/ml_ops.sh

@@ -36,7 +36,6 @@ if [[ "${#FDATE}" != "8" || -z "${DSOURCE}" ]]; then
     exit
 fi
 
-
 # read in variables (except for date) from etc/.conf file
 # note: FDATE and DSOURCE *must* be defined prior sourcing this conf file
 
@@ -90,6 +89,7 @@ time spark-submit --class "org.apache.spot.SuspiciousConnects" \
   --conf spark.dynamicAllocation.enabled=true \
   --conf spark.executor.cores=${SPK_EXEC_CORES} \
   --conf spark.executor.memory=${SPK_EXEC_MEM} \
+  --conf spark.sql.autoBroadcastJoinThreshold=${SPK_AUTO_BRDCST_JOIN_THR} \
   --conf "spark.executor.extraJavaOptions=-XX:MaxPermSize=512M -XX:PermSize=512M" \
   --conf spark.kryoserializer.buffer.max=512m \
   --conf spark.yarn.am.waitTime=100s \
@@ -104,5 +104,6 @@ time spark-submit --class "org.apache.spot.SuspiciousConnects" \
   --threshold ${TOL} \
   --maxresults ${MAXRESULTS} \
   --ldamaxiterations 20 \
+  --precision ${PRECISION} \
   $USER_DOMAIN_CMD
 

spot-ml/ml_test.sh

@@ -35,6 +35,14 @@ LPATH=${LUSER}/ml/${DSOURCE}/test
 HPATH=${HUSER}/${DSOURCE}/test/scored_results
 # prepare parameters pipeline stages
 
+# pass the user domain designation if not empty
+
+if [ ! -z $USER_DOMAIN ] ; then
+    USER_DOMAIN_CMD="--userdomain $USER_DOMAIN"
+else
+    USER_DOMAIN_CMD=''
+fi
+
 FEEDBACK_PATH=${LPATH}/${DSOURCE}_scores.csv
 
 HDFS_SCORED_CONNECTS=${HPATH}/scores
@@ -47,20 +55,17 @@ hdfs dfs -rm -R -f ${HDFS_SCORED_CONNECTS}
 time spark-submit --class "org.apache.spot.SuspiciousConnects" \
   --master yarn-client \
   --driver-memory ${SPK_DRIVER_MEM} \
+  --num-executors ${SPK_EXEC} \
   --conf spark.driver.maxResultSize=${SPK_DRIVER_MAX_RESULTS} \
   --conf spark.driver.maxPermSize=512m \
-  --conf spark.driver.cores=1 \
   --conf spark.dynamicAllocation.enabled=true \
-  --conf spark.dynamicAllocation.minExecutors=1 \
-  --conf spark.dynamicAllocation.maxExecutors=${SPK_EXEC} \
   --conf spark.executor.cores=${SPK_EXEC_CORES} \
   --conf spark.executor.memory=${SPK_EXEC_MEM} \
+  --conf spark.sql.autoBroadcastJoinThreshold=${SPK_AUTO_BRDCST_JOIN_THR} \
   --conf "spark.executor.extraJavaOptions=-XX:MaxPermSize=512M -XX:PermSize=512M" \
-  --conf spark.shuffle.io.preferDirectBufs=false    \
   --conf spark.kryoserializer.buffer.max=512m \
-  --conf spark.shuffle.service.enabled=true \
-  --conf spark.yarn.am.waitTime=1000000 \
-  --conf spark.yarn.driver.memoryOverhead=${SPK_DRIVER_MEM_OVERHEAD} \
+  --conf spark.yarn.am.waitTime=100s \
+  --conf spark.yarn.am.memoryOverhead=${SPK_DRIVER_MEM_OVERHEAD} \
   --conf spark.yarn.executor.memoryOverhead=${SPK_EXEC_MEM_OVERHEAD} target/scala-2.10/spot-ml-assembly-1.1.jar \
   --analysis ${DSOURCE} \
   --input ${RAWDATA_PATH}  \
@@ -70,4 +75,6 @@ time spark-submit --class "org.apache.spot.SuspiciousConnects" \
   --scored ${HDFS_SCORED_CONNECTS} \
   --threshold ${TOL} \
   --maxresults ${MAXRESULTS} \
-  --ldamaxiterations 11
+  --ldamaxiterations 20 \
+  --precision ${PRECISION} \
+  $USER_DOMAIN_CMD

spot-ml/src/main/scala/org/apache/spot/SuspiciousConnectsArgumentParser.scala

@@ -17,27 +17,14 @@
 
 package org.apache.spot
 
+import org.apache.spot.utilities.{FloatPointPrecisionUtility, FloatPointPrecisionUtility32, FloatPointPrecisionUtility64}
+
 
 /**
   * Parses arguments for the suspicious connections analysis.
   */
 object SuspiciousConnectsArgumentParser {
 
-  case class SuspiciousConnectsConfig(analysis: String = "",
-                                      inputPath: String = "",
-                                      feedbackFile: String = "",
-                                      duplicationFactor: Int = 1,
-                                      topicCount: Int = 20,
-                                      userDomain: String = "",
-                                      hdfsScoredConnect: String = "",
-                                      threshold: Double = 1.0d,
-                                      maxResults: Int = -1,
-                                      outputDelimiter: String = "\t",
-                                      ldaPRGSeed: Option[Long] = None,
-                                      ldaMaxiterations: Int = 20,
-                                      ldaAlpha: Double = 1.02,
-                                      ldaBeta: Double = 1.001)
-
   val parser: scopt.OptionParser[SuspiciousConnectsConfig] = new scopt.OptionParser[SuspiciousConnectsConfig]("LDA") {
 
     head("LDA Process", "1.1")
@@ -99,5 +86,28 @@ object SuspiciousConnectsArgumentParser {
     opt[Double]("ldabeta").optional().valueName("float64").
       action((x, c) => c.copy(ldaBeta = x)).
       text("topic concentration for lda, default 1.001")
+
+    opt[Int]("precision").optional().valueName("int").
+      action((x, c) => c.copy(precisionUtility = x match {
+        case 32 => FloatPointPrecisionUtility32
+        case 64 => FloatPointPrecisionUtility64
+        case _ => FloatPointPrecisionUtility64
+      }))
   }
+
+  case class SuspiciousConnectsConfig(analysis: String = "",
+                                      inputPath: String = "",
+                                      feedbackFile: String = "",
+                                      duplicationFactor: Int = 1,
+                                      topicCount: Int = 20,
+                                      userDomain: String = "",
+                                      hdfsScoredConnect: String = "",
+                                      threshold: Double = 1.0d,
+                                      maxResults: Int = -1,
+                                      outputDelimiter: String = "\t",
+                                      ldaPRGSeed: Option[Long] = None,
+                                      ldaMaxiterations: Int = 20,
+                                      ldaAlpha: Double = 1.02,
+                                      ldaBeta: Double = 1.001,
+                                      precisionUtility: FloatPointPrecisionUtility = FloatPointPrecisionUtility64)
 }

spot-ml/src/main/scala/org/apache/spot/SuspiciousConnectsScoreFunction.scala

@@ -18,33 +18,35 @@
 package org.apache.spot
 
 import org.apache.spark.broadcast.Broadcast
+import org.apache.spot.utilities.FloatPointPrecisionUtility
 import org.apache.spot.utilities.data.validation.InvalidDataHandler
 
 /**
   * Base class for scoring suspicious connects models.
   * Assumes that distribution of words is independent of the IP when conditioned on the topic
   * and performs a simple sum over a partition of the space by topic.
   *
-  * @param topicCount Number of topics produced by the topic modelling analysis.
-  * @param ipToTopicMixBC Broadcast of map assigning IPs to topic mixes.
+  * @param topicCount           Number of topics produced by the topic modelling analysis.
   * @param wordToPerTopicProbBC Broadcast of map assigning words to per-topic conditional probability.
   */
 class SuspiciousConnectsScoreFunction(topicCount: Int,
-                                      ipToTopicMixBC: Broadcast[Map[String, Array[Double]]],
                                       wordToPerTopicProbBC: Broadcast[Map[String, Array[Double]]]) extends Serializable {
 
-  def score(ip: String, word: String): Double = {
+  def score[P <: FloatPointPrecisionUtility](precisionUtility: P)
+                                            (documentTopicMix: Seq[precisionUtility.TargetType], word: String): Double = {
 
-    val zeroProb = Array.fill(topicCount) { 0d }
+    val zeroProb = Array.fill(topicCount) {
+      0d
+    }
 
-    if(word == InvalidDataHandler.WordError){
+    if (word == InvalidDataHandler.WordError) {
       InvalidDataHandler.ScoreError
     } else {
       // If either the ip or the word key value cannot be found it means that it was not seen in training.
-      val topicGivenDocProbs = ipToTopicMixBC.value.getOrElse(ip, zeroProb)
-      val wordGivenTopicProbs = wordToPerTopicProbBC.value.getOrElse(word, zeroProb)
+      val wordGivenTopicProbabilities = wordToPerTopicProbBC.value.getOrElse(word, zeroProb)
+      val documentTopicMixDouble: Seq[Double] = precisionUtility.toDoubles(documentTopicMix)
 
-      topicGivenDocProbs.zip(wordGivenTopicProbs)
+      documentTopicMixDouble.zip(wordGivenTopicProbabilities)
         .map({ case (pWordGivenTopic, pTopicGivenDoc) => pWordGivenTopic * pTopicGivenDoc })
         .sum
     }