feat(Audience Evaluation): Audience Logging (#154)

Author: oakbani

src/Optimizely/DecisionService/DecisionService.php

@@ -145,7 +145,7 @@ public function getVariation(Experiment $experiment, $userId, $attributes = null
             }
         }
 
-        if (!Validator::isUserInExperiment($this->_projectConfig, $experiment, $attributes)) {
+        if (!Validator::isUserInExperiment($this->_projectConfig, $experiment, $attributes, $this->_logger)) {
             $this->_logger->log(
                 Logger::INFO,
                 sprintf('User "%s" does not meet conditions to be in experiment "%s".', $userId, $experiment->getKey())
@@ -188,10 +188,10 @@ public function getVariationForFeature(FeatureFlag $featureFlag, $userId, $userA
                 Logger::INFO,
                 "User '{$userId}' is bucketed into rollout for feature flag '{$featureFlag->getKey()}'."
             );
-      
+
             return $decision;
         }
-            
+
         $this->_logger->log(
             Logger::INFO,
             "User '{$userId}' is not bucketed into rollout for feature flag '{$featureFlag->getKey()}'."
@@ -291,7 +291,7 @@ public function getVariationForFeatureRollout(FeatureFlag $featureFlag, $userId,
             $experiment = $rolloutRules[$i];
 
             // Evaluate if user meets the audience condition of this rollout rule
-            if (!Validator::isUserInExperiment($this->_projectConfig, $experiment, $userAttributes)) {
+            if (!Validator::isUserInExperiment($this->_projectConfig, $experiment, $userAttributes, $this->_logger)) {
                 $this->_logger->log(
                     Logger::DEBUG,
                     sprintf("User '%s' did not meet the audience conditions to be in rollout rule '%s'.", $userId, $experiment->getKey())
@@ -309,16 +309,16 @@ public function getVariationForFeatureRollout(FeatureFlag $featureFlag, $userId,
         }
         // Evaluate Everyone Else Rule / Last Rule now
         $experiment = $rolloutRules[sizeof($rolloutRules)-1];
-        
+
         // Evaluate if user meets the audience condition of Everyone Else Rule / Last Rule now
-        if (!Validator::isUserInExperiment($this->_projectConfig, $experiment, $userAttributes)) {
+        if (!Validator::isUserInExperiment($this->_projectConfig, $experiment, $userAttributes, $this->_logger)) {
             $this->_logger->log(
                 Logger::DEBUG,
                 sprintf("User '%s' did not meet the audience conditions to be in rollout rule '%s'.", $userId, $experiment->getKey())
             );
             return null;
         }
-        
+
         $variation = $this->_bucketer->bucket($this->_projectConfig, $experiment, $bucketing_id, $userId);
         if ($variation && $variation->getKey()) {
             return new FeatureDecision($experiment, $variation, FeatureDecision::DECISION_SOURCE_ROLLOUT);

src/Optimizely/Enums/AudienceEvaluationLogs.php

@@ -0,0 +1,34 @@
+<?php
+/**
+ * Copyright 2019, Optimizely
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace Optimizely\Enums;
+
+class AudienceEvaluationLogs
+{
+    const AUDIENCE_EVALUATION_RESULT = "Audience \"%s\" evaluated to %s.";
+    const AUDIENCE_EVALUATION_RESULT_COMBINED = "Audiences for experiment \"%s\" collectively evaluated to %s.";
+    const EVALUATING_AUDIENCES_COMBINED = "Evaluating audiences for experiment \"%s\": %s.";
+    const EVALUATING_AUDIENCE = "Starting to evaluate audience \"%s\" with conditions: %s.";
+    const INFINITE_ATTRIBUTE_VALUE = "Audience condition %s evaluated to UNKNOWN because the number value for user attribute \"%s\" is not in the range [-2^53, +2^53].";
+    const MISSING_ATTRIBUTE_VALUE = "Audience condition %s evaluated to UNKNOWN because no value was passed for user attribute \"%s\".";
+    const NULL_ATTRIBUTE_VALUE = "Audience condition %s evaluated to UNKNOWN because a null value was passed for user attribute \"%s\".";
+    const UNEXPECTED_TYPE = "Audience condition %s evaluated to UNKNOWN because a value of type \"%s\" was passed for user attribute \"%s\".";
+
+    const UNKNOWN_CONDITION_TYPE = "Audience condition %s uses an unknown condition type. You may need to upgrade to a newer release of the Optimizely SDK.";
+    const UNKNOWN_CONDITION_VALUE = "Audience condition %s has an unsupported condition value. You may need to upgrade to a newer release of the Optimizely SDK.";
+    const UNKNOWN_MATCH_TYPE = "Audience condition %s uses an unknown match type. You may need to upgrade to a newer release of the Optimizely SDK.";
+}

src/Optimizely/Utils/CustomAttributeConditionEvaluator.php

@@ -17,6 +17,8 @@
 
 namespace Optimizely\Utils;
 
+use Monolog\Logger;
+use Optimizely\Enums\AudienceEvaluationLogs as logs;
 use Optimizely\Utils\Validator;
 
 class CustomAttributeConditionEvaluator
@@ -31,17 +33,19 @@ class CustomAttributeConditionEvaluator
 
     /**
      * @var UserAttributes
-     */
+    */
     protected $userAttributes;
 
     /**
      * CustomAttributeConditionEvaluator constructor
      *
      * @param array $userAttributes Associative array of user attributes to values.
+     * @param $logger LoggerInterface.
      */
-    public function __construct(array $userAttributes)
+    public function __construct(array $userAttributes, $logger)
     {
         $this->userAttributes = $userAttributes;
+        $this->logger = $logger;
     }
 
     /**
@@ -73,7 +77,7 @@ protected function getMatchTypes()
     /**
      * Gets the evaluator method name for the given match type.
      *
-     * @param string $matchType Match type for which to get evaluator.
+     * @param  string $matchType Match type for which to get evaluator.
      *
      * @return string Corresponding evaluator method name.
      */
@@ -92,13 +96,13 @@ protected function getEvaluatorByMatchType($matchType)
     /**
      * Checks if the given input is a valid value for exact condition evaluation.
      *
-     * @param $value Input to check.
+     * @param  $value Input to check.
      *
-     * @return boolean true if given input is a string/boolean/finite number, false otherwise.
+     * @return boolean true if given input is a string/boolean/number, false otherwise.
      */
-    protected function isValueValidForExactConditions($value)
+    protected function isValueTypeValidForExactConditions($value)
     {
-        if (is_string($value) || is_bool($value) || Validator::isFiniteNumber($value)) {
+        if (is_string($value) || is_bool($value) || is_int($value) || is_float($value)) {
             return true;
         }
 
@@ -108,7 +112,7 @@ protected function isValueValidForExactConditions($value)
     /**
      * Evaluate the given exact match condition for the given user attributes.
      *
-     * @param object $condition
+     * @param  object $condition
      *
      * @return null|boolean true if the user attribute value is equal (===) to the condition value,
      *                      false if the user attribute value is not equal (!==) to the condition value,
@@ -122,11 +126,34 @@ protected function exactEvaluator($condition)
         $conditionValue = $condition['value'];
         $userValue = isset($this->userAttributes[$conditionName]) ? $this->userAttributes[$conditionName]: null;
 
-        if (!$this->isValueValidForExactConditions($userValue)
-            || !$this->isValueValidForExactConditions($conditionValue)
-            || !Validator::areValuesSameType($conditionValue, $userValue)
-        ) {
-                return null;
+        if (!$this->isValueTypeValidForExactConditions($conditionValue) ||
+            ((is_int($conditionValue) || is_float($conditionValue)) && !Validator::isFiniteNumber($conditionValue))) {
+            $this->logger->log(Logger::WARNING, sprintf(
+                logs::UNKNOWN_CONDITION_VALUE,
+                json_encode($condition)
+            ));
+            return null;
+        }
+
+        if (!$this->isValueTypeValidForExactConditions($userValue) ||
+            !Validator::areValuesSameType($conditionValue, $userValue)) {
+            $this->logger->log(Logger::WARNING, sprintf(
+                logs::UNEXPECTED_TYPE,
+                json_encode($condition),
+                gettype($userValue),
+                $conditionName
+            ));
+            return null;
+        }
+
+        if ((is_int($userValue) || is_float($userValue)) &&
+            !Validator::isFiniteNumber($userValue)) {
+            $this->logger->log(Logger::WARNING, sprintf(
+                logs::INFINITE_ATTRIBUTE_VALUE,
+                json_encode($condition),
+                $conditionName
+            ));
+            return null;
         }
 
         return $conditionValue == $userValue;
@@ -135,7 +162,7 @@ protected function exactEvaluator($condition)
     /**
      * Evaluate the given exists match condition for the given user attributes.
      *
-     * @param object $condition
+     * @param  object $condition
      *
      * @return null|boolean true if both:
      *                           1) the user attributes have a value for the given condition, and
@@ -151,7 +178,7 @@ protected function existsEvaluator($condition)
     /**
      * Evaluate the given greater than match condition for the given user attributes.
      *
-     * @param object $condition
+     * @param  object $condition
      *
      * @return boolean true if the user attribute value is greater than the condition value,
      *                 false if the user attribute value is less than or equal to the condition value,
@@ -164,7 +191,30 @@ protected function greaterThanEvaluator($condition)
         $conditionValue = $condition['value'];
         $userValue = isset($this->userAttributes[$conditionName]) ? $this->userAttributes[$conditionName]: null;
 
-        if (!Validator::isFiniteNumber($userValue) || !Validator::isFiniteNumber($conditionValue)) {
+        if (!Validator::isFiniteNumber($conditionValue)) {
+            $this->logger->log(Logger::WARNING, sprintf(
+                logs::UNKNOWN_CONDITION_VALUE,
+                json_encode($condition)
+            ));
+            return null;
+        }
+
+        if (!(is_int($userValue) || is_float($userValue))) {
+            $this->logger->log(Logger::WARNING, sprintf(
+                logs::UNEXPECTED_TYPE,
+                json_encode($condition),
+                gettype($userValue),
+                $conditionName
+            ));
+            return null;
+        }
+
+        if (!Validator::isFiniteNumber($userValue)) {
+            $this->logger->log(Logger::WARNING, sprintf(
+                logs::INFINITE_ATTRIBUTE_VALUE,
+                json_encode($condition),
+                $conditionName
+            ));
             return null;
         }
 
@@ -174,7 +224,7 @@ protected function greaterThanEvaluator($condition)
     /**
      * Evaluate the given less than match condition for the given user attributes.
      *
-     * @param object $condition
+     * @param  object $condition
      *
      * @return boolean true if the user attribute value is less than the condition value,
      *                 false if the user attribute value is greater than or equal to the condition value,
@@ -187,30 +237,67 @@ protected function lessThanEvaluator($condition)
         $conditionValue = $condition['value'];
         $userValue = isset($this->userAttributes[$conditionName]) ? $this->userAttributes[$conditionName]: null;
 
-        if (!Validator::isFiniteNumber($userValue) || !Validator::isFiniteNumber($conditionValue)) {
+        if (!Validator::isFiniteNumber($conditionValue)) {
+            $this->logger->log(Logger::WARNING, sprintf(
+                logs::UNKNOWN_CONDITION_VALUE,
+                json_encode($condition)
+            ));
+            return null;
+        }
+
+        if (!(is_int($userValue) || is_float($userValue))) {
+            $this->logger->log(Logger::WARNING, sprintf(
+                logs::UNEXPECTED_TYPE,
+                json_encode($condition),
+                gettype($userValue),
+                $conditionName
+            ));
+            return null;
+        }
+
+        if (!Validator::isFiniteNumber($userValue)) {
+            $this->logger->log(Logger::WARNING, sprintf(
+                logs::INFINITE_ATTRIBUTE_VALUE,
+                json_encode($condition),
+                $conditionName
+            ));
             return null;
         }
 
         return $userValue < $conditionValue;
     }
 
      /**
-      * Evaluate the given substring than match condition for the given user attributes.
-      *
-      * @param object $condition
-      *
-      * @return boolean true if the condition value is a substring of the user attribute value,
-      *                 false if the condition value is not a substring of the user attribute value,
-      *                 null if the condition value isn't a string or the user attribute value
-      *                 isn't a string.
-      */
+     * Evaluate the given substring than match condition for the given user attributes.
+     *
+     * @param  object $condition
+     *
+     * @return boolean true if the condition value is a substring of the user attribute value,
+     *                 false if the condition value is not a substring of the user attribute value,
+     *                 null if the condition value isn't a string or the user attribute value
+     *                 isn't a string.
+     */
     protected function substringEvaluator($condition)
     {
         $conditionName = $condition['name'];
         $conditionValue = $condition['value'];
         $userValue = isset($this->userAttributes[$conditionName]) ? $this->userAttributes[$conditionName]: null;
 
-        if (!is_string($userValue) || !is_string($conditionValue)) {
+        if (!is_string($conditionValue)) {
+            $this->logger->log(Logger::WARNING, sprintf(
+                logs::UNKNOWN_CONDITION_VALUE,
+                json_encode($condition)
+            ));
+            return null;
+        }
+
+        if (!is_string($userValue)) {
+            $this->logger->log(Logger::WARNING, sprintf(
+                logs::UNEXPECTED_TYPE,
+                json_encode($condition),
+                gettype($userValue),
+                $conditionName
+            ));
             return null;
         }
 
@@ -220,7 +307,7 @@ protected function substringEvaluator($condition)
     /**
      * Function to evaluate audience conditions against user's attributes.
      *
-     * @param array $leafCondition Condition to be evaluated.
+     * @param array $leafCondition  Condition to be evaluated.
      *
      * @return null|boolean true/false if the given user attributes match/don't match the given conditions,
      * null if the given user attributes and conditions can't be evaluated.
@@ -230,6 +317,10 @@ public function evaluate($leafCondition)
         $leafCondition = $this->setNullForMissingKeys($leafCondition);
 
         if ($leafCondition['type'] !== self::CUSTOM_ATTRIBUTE_CONDITION_TYPE) {
+            $this->logger->log(Logger::WARNING, sprintf(
+                logs::UNKNOWN_CONDITION_TYPE,
+                json_encode($leafCondition)
+            ));
             return null;
         }
 
@@ -240,9 +331,35 @@ public function evaluate($leafCondition)
         }
 
         if (!in_array($conditionMatch, $this->getMatchTypes())) {
+            $this->logger->log(Logger::WARNING, sprintf(
+                logs::UNKNOWN_MATCH_TYPE,
+                json_encode($leafCondition)
+            ));
             return null;
         }
 
+        $conditionName = $leafCondition['name'];
+
+        if ($leafCondition['match'] !== self::EXISTS_MATCH_TYPE) {
+            if (!array_key_exists($conditionName, $this->userAttributes)) {
+                $this->logger->log(Logger::DEBUG, sprintf(
+                    logs::MISSING_ATTRIBUTE_VALUE,
+                    json_encode($leafCondition),
+                    $conditionName
+                ));
+                return null;
+            }
+
+            if (!isset($this->userAttributes[$conditionName])) {
+                $this->logger->log(Logger::DEBUG, sprintf(
+                    logs::NULL_ATTRIBUTE_VALUE,
+                    json_encode($leafCondition),
+                    $conditionName
+                ));
+                return null;
+            }
+        }
+
         $evaluatorForMatch = $this->getEvaluatorByMatchType($conditionMatch);
         return $this->$evaluatorForMatch($leafCondition);
     }