feat: add logger field to client configs for user defined sdk logging behavior

Author: kyeh-amp

src/amplitude_experiment/local/client.py

@@ -1,4 +1,3 @@
-import logging
 from threading import Lock
 from typing import Any, List, Dict, Set
 
@@ -47,10 +46,7 @@ def __init__(self, api_key: str, config: LocalEvaluationConfig = None):
             instance = Amplitude(config.assignment_config.api_key, config.assignment_config)
             self.assignment_service = AssignmentService(instance, AssignmentFilter(
                 config.assignment_config.cache_capacity), config.assignment_config.send_evaluated_props)
-        self.logger = logging.getLogger("Amplitude")
-        self.logger.addHandler(logging.StreamHandler())
-        if self.config.debug:
-            self.logger.setLevel(logging.DEBUG)
+        self.logger = self.config.logger
         self.__setup_connection_pool()
         self.lock = Lock()
         self.cohort_storage = InMemoryCohortStorage()

src/amplitude_experiment/local/config.py

@@ -1,27 +1,38 @@
+import logging
+import sys
+
 from ..assignment import AssignmentConfig
-from ..cohort.cohort_sync_config import CohortSyncConfig, DEFAULT_COHORT_SYNC_URL, EU_COHORT_SYNC_URL
+from ..cohort.cohort_sync_config import (
+    CohortSyncConfig,
+    DEFAULT_COHORT_SYNC_URL,
+    EU_COHORT_SYNC_URL,
+)
 from ..server_zone import ServerZone
 
-DEFAULT_SERVER_URL = 'https://api.lab.amplitude.com'
-EU_SERVER_URL = 'https://flag.lab.eu.amplitude.com'
+DEFAULT_SERVER_URL = "https://api.lab.amplitude.com"
+EU_SERVER_URL = "https://flag.lab.eu.amplitude.com"
 
-DEFAULT_STREAM_URL = 'https://stream.lab.amplitude.com'
-EU_STREAM_SERVER_URL = 'https://stream.lab.eu.amplitude.com'
+DEFAULT_STREAM_URL = "https://stream.lab.amplitude.com"
+EU_STREAM_SERVER_URL = "https://stream.lab.eu.amplitude.com"
 
 
 class LocalEvaluationConfig:
     """Experiment Local Client Configuration"""
 
-    def __init__(self, debug: bool = False,
-                 server_url: str = DEFAULT_SERVER_URL,
-                 server_zone: ServerZone = ServerZone.US,
-                 flag_config_polling_interval_millis: int = 30000,
-                 flag_config_poller_request_timeout_millis: int = 10000,
-                 stream_updates: bool = False,
-                 stream_server_url: str = DEFAULT_STREAM_URL,
-                 stream_flag_conn_timeout: int = 1500,
-                 assignment_config: AssignmentConfig = None,
-                 cohort_sync_config: CohortSyncConfig = None):
+    def __init__(
+        self,
+        debug: bool = False,
+        server_url: str = DEFAULT_SERVER_URL,
+        server_zone: ServerZone = ServerZone.US,
+        flag_config_polling_interval_millis: int = 30000,
+        flag_config_poller_request_timeout_millis: int = 10000,
+        stream_updates: bool = False,
+        stream_server_url: str = DEFAULT_STREAM_URL,
+        stream_flag_conn_timeout: int = 1500,
+        assignment_config: AssignmentConfig = None,
+        cohort_sync_config: CohortSyncConfig = None,
+        logger: logging.Logger = None,
+    ):
         """
         Initialize a config
            Parameters:
@@ -34,6 +45,8 @@ def __init__(self, debug: bool = False,
                   fetching flag configurations.
                 assignment_config (AssignmentConfig): The assignment configuration.
                 cohort_sync_config (CohortSyncConfig): The cohort sync configuration.
+                logger (logging.Logger): Optional logger instance. If provided, this logger will be used instead of
+                  creating a new one. The debug flag will still be applied to set the log level.
 
            Returns:
                The config object
@@ -44,16 +57,35 @@ def __init__(self, debug: bool = False,
         self.cohort_sync_config = cohort_sync_config
         if server_url == DEFAULT_SERVER_URL and server_zone == ServerZone.EU:
             self.server_url = EU_SERVER_URL
-            if (cohort_sync_config is not None and
-                    cohort_sync_config.cohort_server_url == DEFAULT_COHORT_SYNC_URL):
+            if (
+                cohort_sync_config is not None
+                and cohort_sync_config.cohort_server_url == DEFAULT_COHORT_SYNC_URL
+            ):
                 self.cohort_sync_config.cohort_server_url = EU_COHORT_SYNC_URL
 
         self.stream_server_url = stream_server_url
         if stream_server_url == DEFAULT_SERVER_URL and server_zone == ServerZone.EU:
             self.stream_server_url = EU_STREAM_SERVER_URL
 
         self.flag_config_polling_interval_millis = flag_config_polling_interval_millis
-        self.flag_config_poller_request_timeout_millis = flag_config_poller_request_timeout_millis
+        self.flag_config_poller_request_timeout_millis = (
+            flag_config_poller_request_timeout_millis
+        )
         self.stream_updates = stream_updates
         self.stream_flag_conn_timeout = stream_flag_conn_timeout
         self.assignment_config = assignment_config
+
+        # Set up logger: use provided logger or create default one
+        if logger is None:
+            self.logger = logging.getLogger("Amplitude")
+            # Only add handler if logger doesn't already have one
+            if not self.logger.handlers:
+                handler = logging.StreamHandler(sys.stderr)
+                self.logger.addHandler(handler)
+        else:
+            self.logger = logger
+
+        # Set log level: DEBUG if debug=True, otherwise WARNING
+        # This applies to both provided loggers and the default logger
+        log_level = logging.DEBUG if self.debug else logging.WARNING
+        self.logger.setLevel(log_level)

src/amplitude_experiment/remote/client.py

@@ -1,5 +1,4 @@
 import json
-import logging
 import threading
 import time
 from time import sleep
@@ -32,10 +31,7 @@ def __init__(self, api_key, config=None):
             raise ValueError("Experiment API key is empty")
         self.api_key = api_key
         self.config = config or RemoteEvaluationConfig()
-        self.logger = logging.getLogger("Amplitude")
-        self.logger.addHandler(logging.StreamHandler())
-        if self.config.debug:
-            self.logger.setLevel(logging.DEBUG)
+        self.logger = self.config.logger
         self.__setup_connection_pool()
 
     def fetch_v2(self, user: User):

src/amplitude_experiment/remote/config.py

@@ -1,20 +1,27 @@
 from ..server_zone import ServerZone
 
-DEFAULT_SERVER_URL = 'https://api.lab.amplitude.com'
-EU_SERVER_URL = 'https://api.lab.eu.amplitude.com'
+DEFAULT_SERVER_URL = "https://api.lab.amplitude.com"
+EU_SERVER_URL = "https://api.lab.eu.amplitude.com"
+import logging
+import sys
+
 
 class RemoteEvaluationConfig:
     """Experiment Remote Client Configuration"""
 
-    def __init__(self, debug=False,
-                 server_url=DEFAULT_SERVER_URL,
-                 fetch_timeout_millis=10000,
-                 fetch_retries=0,
-                 fetch_retry_backoff_min_millis=500,
-                 fetch_retry_backoff_max_millis=10000,
-                 fetch_retry_backoff_scalar=1.5,
-                 fetch_retry_timeout_millis=10000,
-                 server_zone: ServerZone = ServerZone.US):
+    def __init__(
+        self,
+        debug=False,
+        server_url=DEFAULT_SERVER_URL,
+        fetch_timeout_millis=10000,
+        fetch_retries=0,
+        fetch_retry_backoff_min_millis=500,
+        fetch_retry_backoff_max_millis=10000,
+        fetch_retry_backoff_scalar=1.5,
+        fetch_retry_timeout_millis=10000,
+        server_zone: ServerZone = ServerZone.US,
+        logger=None,
+    ):
         """
         Initialize a config
             Parameters:
@@ -30,6 +37,8 @@ def __init__(self, debug=False,
                 fetch_retry_backoff_scalar (float): Scales the minimum backoff exponentially.
                 fetch_retry_timeout_millis (int): The request timeout for retrying fetch requests.
                 server_zone (str): Select the Amplitude data center to get flags and variants from, US or EU.
+                logger (logging.Logger): Optional logger instance. If provided, this logger will be used instead of
+                  creating a new one. The debug flag will still be applied to set the log level.
 
             Returns:
                 The config object
@@ -46,3 +55,17 @@ def __init__(self, debug=False,
         if server_url == DEFAULT_SERVER_URL and server_zone == ServerZone.EU:
             self.server_url = EU_SERVER_URL
 
+        # Set up logger: use provided logger or create default one
+        if logger is None:
+            self.logger = logging.getLogger("Amplitude")
+            # Only add handler if logger doesn't already have one
+            if not self.logger.handlers:
+                handler = logging.StreamHandler(sys.stderr)
+                self.logger.addHandler(handler)
+        else:
+            self.logger = logger
+
+        # Set log level: DEBUG if debug=True, otherwise WARNING
+        # This applies to both provided loggers and the default logger
+        log_level = logging.DEBUG if self.debug else logging.WARNING
+        self.logger.setLevel(log_level)

tests/local/config_test.py

@@ -0,0 +1,74 @@
+import io
+import logging
+import sys
+import unittest
+
+from src.amplitude_experiment.local.config import LocalEvaluationConfig
+
+
+class LocalEvaluationConfigLoggerTestCase(unittest.TestCase):
+    """Tests for LocalEvaluationConfig logger configuration"""
+
+    def setUp(self):
+        """Clear existing handlers from the Amplitude logger before each test"""
+        logger = logging.getLogger("Amplitude")
+        logger.handlers.clear()
+        logger.setLevel(logging.NOTSET)
+
+    def tearDown(self):
+        """Clean up handlers after each test"""
+        logger = logging.getLogger("Amplitude")
+        logger.handlers.clear()
+
+    def test_default_logger_has_warning_level(self):
+        """Test that default logger has WARNING level and stderr handler when debug=False"""
+        config = LocalEvaluationConfig(debug=False)
+        self.assertEqual(config.logger.level, logging.WARNING)
+        self.assertEqual(len(config.logger.handlers), 1)
+        handler = config.logger.handlers[0]
+        self.assertIsInstance(handler, logging.StreamHandler)
+        self.assertEqual(handler.stream, sys.stderr)
+
+    def test_default_logger_has_debug_level_when_debug_true(self):
+        """Test that default logger has DEBUG level when debug=True"""
+        config = LocalEvaluationConfig(debug=True)
+        self.assertEqual(config.logger.level, logging.DEBUG)
+
+    def test_custom_logger_is_used(self):
+        """Test that provided custom logger is used"""
+        custom_logger = logging.getLogger("CustomLogger")
+        config = LocalEvaluationConfig(logger=custom_logger)
+        self.assertEqual(config.logger, custom_logger)
+        self.assertEqual(config.logger.name, "CustomLogger")
+
+    def test_custom_logger_has_debug_level_when_debug_true(self):
+        """Test that custom logger has DEBUG level set when debug=True"""
+        custom_logger = logging.getLogger("CustomLogger")
+        config = LocalEvaluationConfig(debug=True, logger=custom_logger)
+        self.assertEqual(config.logger.level, logging.DEBUG)
+
+    def test_custom_logger_has_warning_level_when_debug_false(self):
+        """Test that custom logger has WARNING level set when debug=False"""
+        custom_logger = logging.getLogger("CustomLogger")
+        config = LocalEvaluationConfig(debug=False, logger=custom_logger)
+        self.assertEqual(config.logger.level, logging.WARNING)
+
+    def test_custom_logger_debug_flag_takes_precedence(self):
+        """Test that debug flag takes precedence over logger's existing level"""
+        custom_logger = logging.getLogger("CustomLogger")
+        custom_logger.setLevel(logging.ERROR)
+        config = LocalEvaluationConfig(debug=True, logger=custom_logger)
+        # Debug flag should override to DEBUG
+        self.assertEqual(config.logger.level, logging.DEBUG)
+
+    def test_default_logger_only_one_handler_added(self):
+        """Test that only one handler is added to default logger"""
+        config1 = LocalEvaluationConfig()
+        config2 = LocalEvaluationConfig()
+        # Both should use the same logger instance (singleton)
+        logger = logging.getLogger("Amplitude")
+        # Should only have one handler even after creating multiple configs
+        self.assertEqual(len(logger.handlers), 1)
+
+if __name__ == '__main__':
+    unittest.main()

tests/remote/config_test.py

@@ -0,0 +1,74 @@
+import io
+import logging
+import sys
+import unittest
+
+from src.amplitude_experiment.remote.config import RemoteEvaluationConfig
+
+
+class RemoteEvaluationConfigLoggerTestCase(unittest.TestCase):
+    """Tests for RemoteEvaluationConfig logger configuration"""
+
+    def setUp(self):
+        """Clear existing handlers from the Amplitude logger before each test"""
+        logger = logging.getLogger("Amplitude")
+        logger.handlers.clear()
+        logger.setLevel(logging.NOTSET)
+
+    def tearDown(self):
+        """Clean up handlers after each test"""
+        logger = logging.getLogger("Amplitude")
+        logger.handlers.clear()
+
+    def test_default_logger_has_warning_level(self):
+        """Test that default logger has WARNING level and stderr handler when debug=False"""
+        config = RemoteEvaluationConfig(debug=False)
+        self.assertEqual(config.logger.level, logging.WARNING)
+        self.assertEqual(len(config.logger.handlers), 1)
+        handler = config.logger.handlers[0]
+        self.assertIsInstance(handler, logging.StreamHandler)
+        self.assertEqual(handler.stream, sys.stderr)
+
+    def test_default_logger_has_debug_level_when_debug_true(self):
+        """Test that default logger has DEBUG level when debug=True"""
+        config = RemoteEvaluationConfig(debug=True)
+        self.assertEqual(config.logger.level, logging.DEBUG)
+
+    def test_custom_logger_is_used(self):
+        """Test that provided custom logger is used"""
+        custom_logger = logging.getLogger("CustomLogger")
+        config = RemoteEvaluationConfig(logger=custom_logger)
+        self.assertEqual(config.logger, custom_logger)
+        self.assertEqual(config.logger.name, "CustomLogger")
+
+    def test_custom_logger_has_debug_level_when_debug_true(self):
+        """Test that custom logger has DEBUG level set when debug=True"""
+        custom_logger = logging.getLogger("CustomLogger")
+        config = RemoteEvaluationConfig(debug=True, logger=custom_logger)
+        self.assertEqual(config.logger.level, logging.DEBUG)
+
+    def test_custom_logger_has_warning_level_when_debug_false(self):
+        """Test that custom logger has WARNING level set when debug=False"""
+        custom_logger = logging.getLogger("CustomLogger")
+        config = RemoteEvaluationConfig(debug=False, logger=custom_logger)
+        self.assertEqual(config.logger.level, logging.WARNING)
+
+    def test_custom_logger_debug_flag_takes_precedence(self):
+        """Test that debug flag takes precedence over logger's existing level"""
+        custom_logger = logging.getLogger("CustomLogger")
+        custom_logger.setLevel(logging.ERROR)
+        config = RemoteEvaluationConfig(debug=True, logger=custom_logger)
+        # Debug flag should override to DEBUG
+        self.assertEqual(config.logger.level, logging.DEBUG)
+
+    def test_default_logger_only_one_handler_added(self):
+        """Test that only one handler is added to default logger"""
+        config1 = RemoteEvaluationConfig()
+        config2 = RemoteEvaluationConfig()
+        # Both should use the same logger instance (singleton)
+        logger = logging.getLogger("Amplitude")
+        # Should only have one handler even after creating multiple configs
+        self.assertEqual(len(logger.handlers), 1)
+
+if __name__ == '__main__':
+    unittest.main()