Tune javadoc - assume ratios

5 files changed, 49 insertions, 41 deletions

diff --git a/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/Cost.java b/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/Cost.java
index 6de1c5371bd..5acd51e0d2e 100644
--- a/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/Cost.java
+++ b/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/Cost.java
@@ -11,25 +11,20 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * Calculate cost, hardware utilization and waste for applications.
+ * Calculate cost, hardware utilization and waste for Vespa.
  * <p>
  * Cost refers to the total cost ownership aka TCO.
  * <p>
  * We define a target utilization for each cluster in an application and compares this
- * to the actual utilization to get a number for ideal cost (if ideally scaled) and waste.
- * <p>
- * The target utilization is defined with the following in mind:
- * 1 Application stats to see contention on CPU above 80%
- * 2 It is scaled for a 50/50 load balancing between two zones (thus must be able to serve the other zone)
- * 3 Peaks are 2x average wrt CPU
- * 4 Memory contention is rising when over 80%
+ * to the actual utilization. Cost is then the TCO for the hardware used multiplied with
+ * the relative utilization. Waste is the difference between target and ideal cost.
  *
  * @author smorgrav
  */
 public interface Cost {
 
     /**
-     * Get application costs for all applications across all zones
+     * Get application costs for all applications across all zones.
      *
      * @return A list of all application costs in all zones
      */
@@ -51,11 +46,11 @@ public interface Cost {
     }
 
     /**
-     * Get application costs for a specific application deployement
+     * Get application costs for a specific application.
      *
      * @param zone The zone - the combination of a environment and region e.g 'test.us-east-1'
      * @param app  ApplicationId e.g tenant:application:instance
-     * @return A list of applications cost in given zone
+     * @return The cost of one application
      */
     default CostApplication getApplicationCost(Zone zone, ApplicationId app)
             throws NotFoundCheckedException {
@@ -73,14 +68,26 @@ public interface Cost {
     }
 
     /**
-     * Provides target utilization - default targets ARE XXX
+     * Provides target utilization - default targets are cased on the following assumptions:
+     *
+     * 1. CPU contention starts to be noticeable at 80% and spikes are 2x average
+     * 2. Query load is perfectly load-balanced between two zones, cpu needs to handle fail-over - thus 2x load
+     * 3. Memory contention (and especially sys cpu usage from memory management) increases after 90%
+     * 4. Memory consumptions spikes over average with ~20%
+     * 5. Memory and disk usage is independent of query load
+     *
+     * The default targets are:
+     * CPU: 0.2
+     * MEM: 0.7
+     * DISK: 0.7
+     * DISKBUSY: 0.3
      *
      * @param zone The zone - the combination of a environment and region e.g 'test.us-east-1'
      * @param app  ApplicationId e.g tenant:application:instance
      * @return Target utilization
      */
     default CostResources getTargetUtilization(Zone zone, ApplicationId app) {
-        return new CostResources(0.8, 0.3, 0.4, 0.3);
+        return new CostResources(0.7, 0.2, 0.7, 0.3);
     }
 
     /**
@@ -90,18 +97,16 @@ public interface Cost {
 
     /**
      * Provides information about the clusters in the application like
-     * what hardware that it is using, the TCO for the hardware and number of hosts.
+     * what hardware that it is using, the TCO for the hardware and the hostnames in the cluster.
      *
      * @param zone The zone - the combination of a environment and region e.g 'test.us-east-1'
      * @param app  ApplicationId e.g tenant:application:instance
-     * @return Map between clusterid -> costclusterinfo
+     * @return Map between clusterid -> info
      */
     Map<String, CostClusterInfo> getClusterInfo(Zone zone, ApplicationId app);
 
     /**
-     * Provides ratio of available hardware used.
-     * <p>
-     * Used to calculate the utilization of the hardware.
+     * Provides the ratio of available hardware used (e.g cpu, mem, disk) each in the range: [0,1].
      *
      * @param zone The zone - the combination of a environment and region e.g 'test.us-east-1'
      * @param app  ApplicationId e.g tenant:application:instance
diff --git a/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/CostApplication.java b/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/CostApplication.java
index 7e683969ccb..89948cc69ac 100644
--- a/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/CostApplication.java
+++ b/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/CostApplication.java
@@ -8,7 +8,7 @@ import java.util.HashMap;
 import java.util.Map;
 
 /**
- * Calcalute cost for for an application instance. I.e one running vespa application in one zone.
+ * Calculates cost for for an application instance.
  *
  * @author smorgrav
  */
diff --git a/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/CostCluster.java b/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/CostCluster.java
index 37bf62e5b9e..6d454d53268 100644
--- a/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/CostCluster.java
+++ b/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/CostCluster.java
@@ -2,8 +2,7 @@
 package com.yahoo.vespa.hosted.controller.api.integration.cost;
 
 /**
- * Calculate tco, waste and result utilization
- * for one cluster within one Vespa application in one zone.
+ * Calculate tco and waste for one cluster within one Vespa application in one zone.
  *
  * @author smorgrav
  */
@@ -16,9 +15,9 @@ public class CostCluster {
     private final CostResources resultUtilization;
 
     /**
-     * @param clusterInfo       Value object with cluster info e.g. hardware tco
-     * @param systemUtilization Utilization of system resources (in percentage)
-     * @param targetUtilization Target utilization (usually < 1.0)
+     * @param clusterInfo       Value object with cluster info e.g. the TCO for the hardware used
+     * @param systemUtilization Utilization of system resources (as ratios)
+     * @param targetUtilization Target utilization (ratios - usually < 1.0)
      */
     public CostCluster(CostClusterInfo clusterInfo,
                        CostResources systemUtilization,
@@ -58,15 +57,15 @@ public class CostCluster {
     }
 
     static CostResources calculateResultUtilization(CostResources system, CostResources target) {
-        double cpu = system.getCpu()/target.getCpu();
-        double mem = system.getMemory()/target.getMemory();
-        double disk = system.getDisk()/target.getDisk();
-        double diskbusy = system.getDiskBusy()/target.getDiskBusy();
+        double cpu = ratio(system.getCpu(),target.getCpu());
+        double mem = ratio(system.getMemory(),target.getMemory());
+        double disk = ratio(system.getDisk(),target.getDisk());
+        double diskbusy = ratio(system.getDiskBusy(),target.getDiskBusy());
 
         return new CostResources(mem, cpu, disk, diskbusy);
     }
 
-    static double ration(double a, double b) {
+    private static double ratio(double a, double b) {
         if (b == 0) return 1;
         return a/b;
     }
diff --git a/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/CostClusterInfo.java b/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/CostClusterInfo.java
index 26b703347f1..0fe408352dc 100644
--- a/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/CostClusterInfo.java
+++ b/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/CostClusterInfo.java
@@ -6,9 +6,8 @@ import com.yahoo.config.provision.Flavor;
 import java.util.List;
 
 /**
- * Value object of static cluster information.
- *
- * Used to calculate cost and annotate results.
+ * Value object of static cluster information, in particular the TCO
+ * of the hardware used for this cluster.
  *
  * @author smorgrav
  */
diff --git a/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/CostResources.java b/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/CostResources.java
index 86cb3448aef..9d75bc1bdc2 100644
--- a/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/CostResources.java
+++ b/controller-api/src/main/java/com/yahoo/vespa/hosted/controller/api/integration/cost/CostResources.java
@@ -15,6 +15,15 @@ public class CostResources {
     private final double diskBusy;
     private final double maxUtilization;
 
+    /**
+     * Resource utilization as ratios. The ratio is normally between 0 and 1 where
+     * one is fully utilized but can be higher as it consumes more than it are guaranteed.
+     *
+     * @param memory Memory utilization
+     * @param cpu  CPU utilization
+     * @param disk  Disk utilization
+     * @param diskBusy Disk busy
+     */
     public CostResources(double memory, double cpu, double disk, double diskBusy) {
         this.memory = memory;
         this.cpu = cpu;
@@ -26,32 +35,28 @@ public class CostResources {
         this.maxUtilization = Math.max(maxUtil, diskBusy);
     }
 
+    /** @return The utilization ratio of the resource that is utilized the most. */
     public double getMaxUtilization() {
         return maxUtilization;
     }
 
+    /** @return The utilization ratio for memory */
     public double getMemory() {
         return memory;
     }
 
+    /** @return The utilization ratio for cpu */
     public double getCpu() {
         return cpu;
     }
 
+    /** @return The utilization ratio for disk */
     public double getDisk() {
         return disk;
     }
 
+    /** @return The disk busy ratio */
     public double getDiskBusy() {
         return diskBusy;
     }
-
-    private void validateUsageRatio(float ratio) {
-        if (ratio < 0) throw new IllegalArgumentException("Usage cannot be negative");
-        if (ratio > 1) throw new IllegalArgumentException("Usage exceed 1 (using more than it has available)");
-    }
-
-    private void validateUtilRatio(float ratio) {
-        if (ratio < 0) throw new IllegalArgumentException("Utilization cannot be negative");
-    }
 }