feat: Add adaptive poll rate interval logic

Signed-off-by: Cagri Yonca <cagri@ibm.com>

Author: CagriYonca

src/instana/collector/base.py

@@ -58,6 +58,7 @@ def __init__(self, agent: Type["BaseAgent"]) -> None:
         self.background_report_lock = threading.RLock()
 
         # Reporting interval for the background thread(s)
+        # Default is 1 but can be changed by the agent options
         self.report_interval = 1
 
         # Flag to indicate if start/shutdown state

src/instana/collector/host.py

@@ -35,6 +35,13 @@ def start(self) -> None:
             )
             return
 
+        # Update report_interval from agent options poll_rate
+        if hasattr(self.agent, "options") and hasattr(self.agent.options, "poll_rate"):
+            self.report_interval = self.agent.options.poll_rate
+            logger.info(
+                f"Collector started with poll_rate: {self.report_interval} second(s)"
+            )
+
         super(HostCollector, self).start()
 
     def prepare_and_report_data(self) -> None:

src/instana/options.py

@@ -351,12 +351,15 @@ class StandardOptions(BaseOptions):
 
     AGENT_DEFAULT_HOST = "localhost"
     AGENT_DEFAULT_PORT = 42699
+    DEFAULT_POLL_RATE = 1
+    MAX_POLL_RATE = 5
 
     def __init__(self, **kwds: Dict[str, Any]) -> None:
         super(StandardOptions, self).__init__()
 
         self.agent_host = os.environ.get("INSTANA_AGENT_HOST", self.AGENT_DEFAULT_HOST)
         self.agent_port = os.environ.get("INSTANA_AGENT_PORT", self.AGENT_DEFAULT_PORT)
+        self.poll_rate = self.DEFAULT_POLL_RATE
 
         if not isinstance(self.agent_port, int):
             self.agent_port = int(self.agent_port)
@@ -516,6 +519,32 @@ def set_from(self, res_data: Dict[str, Any]) -> None:
             logger.debug(f"options.set_from: Wrong data type - {type(res_data)}")
             return
 
+        # Extract poll_rate from plugin.python.poll_rate
+        if "plugin" in res_data and isinstance(res_data["plugin"], dict):
+            if "python" in res_data["plugin"] and isinstance(
+                res_data["plugin"]["python"], dict
+            ):
+                poll_rate_value = res_data["plugin"]["python"].get("poll_rate")
+                if poll_rate_value is not None:
+                    try:
+                        poll_rate = int(poll_rate_value)
+                        # Validate: only 1 or 5 are allowed
+                        if poll_rate in (self.DEFAULT_POLL_RATE, self.MAX_POLL_RATE):
+                            self.poll_rate = poll_rate
+                            logger.debug(
+                                f"Poll rate set to {self.poll_rate} seconds from agent configuration"
+                            )
+                        else:
+                            logger.debug(
+                                f"Invalid poll_rate value {poll_rate}, defaulting to {self.DEFAULT_POLL_RATE}"
+                            )
+                            self.poll_rate = self.DEFAULT_POLL_RATE
+                    except (ValueError, TypeError):
+                        logger.debug(
+                            f"Invalid poll_rate type, defaulting to {self.DEFAULT_POLL_RATE}"
+                        )
+                        self.poll_rate = self.DEFAULT_POLL_RATE
+
         if "secrets" in res_data:
             self.set_secrets(res_data["secrets"])
 

tests/test_options.py

@@ -1003,6 +1003,147 @@ def test_set_from_bool(
         assert self.standart_options.span_filters == {"exclude": INTERNAL_SPAN_FILTERS}
         assert not self.standart_options.extra_http_headers
 
+    def test_default_poll_rate(self) -> None:
+        """Test that default poll_rate is 1 second"""
+        self.standart_options = StandardOptions()
+        assert self.standart_options.poll_rate == 1
+
+    def test_set_from_with_valid_poll_rate_1(
+        self,
+        caplog: pytest.LogCaptureFixture,
+    ) -> None:
+        """Test setting poll_rate to 1 from announce response"""
+        caplog.set_level(logging.DEBUG, logger="instana")
+        caplog.clear()
+
+        self.standart_options = StandardOptions()
+        test_res_data = {"plugin": {"python": {"poll_rate": 1}}}
+        self.standart_options.set_from(test_res_data)
+
+        assert self.standart_options.poll_rate == 1
+        assert "Poll rate set to 1 seconds from agent configuration" in caplog.messages
+
+    def test_set_from_with_valid_poll_rate_5(
+        self,
+        caplog: pytest.LogCaptureFixture,
+    ) -> None:
+        """Test setting poll_rate to 5 from announce response"""
+        caplog.set_level(logging.DEBUG, logger="instana")
+        caplog.clear()
+
+        self.standart_options = StandardOptions()
+        test_res_data = {"plugin": {"python": {"poll_rate": 5}}}
+        self.standart_options.set_from(test_res_data)
+
+        assert self.standart_options.poll_rate == 5
+        assert "Poll rate set to 5 seconds from agent configuration" in caplog.messages
+
+    def test_set_from_with_invalid_poll_rate_defaults_to_1(
+        self,
+        caplog: pytest.LogCaptureFixture,
+    ) -> None:
+        """Test that invalid poll_rate values default to 1"""
+        caplog.set_level(logging.DEBUG, logger="instana")
+
+        # Test with poll_rate = 10
+        caplog.clear()
+        self.standart_options = StandardOptions()
+        test_res_data = {"plugin": {"python": {"poll_rate": 10}}}
+        self.standart_options.set_from(test_res_data)
+        assert self.standart_options.poll_rate == 1
+        assert "Invalid poll_rate value 10, defaulting to 1" in caplog.messages
+
+        # Test with poll_rate = 0
+        caplog.clear()
+        self.standart_options = StandardOptions()
+        test_res_data = {"plugin": {"python": {"poll_rate": 0}}}
+        self.standart_options.set_from(test_res_data)
+        assert self.standart_options.poll_rate == 1
+        assert "Invalid poll_rate value 0, defaulting to 1" in caplog.messages
+
+        # Test with poll_rate = -5
+        caplog.clear()
+        self.standart_options = StandardOptions()
+        test_res_data = {"plugin": {"python": {"poll_rate": -5}}}
+        self.standart_options.set_from(test_res_data)
+        assert self.standart_options.poll_rate == 1
+        assert "Invalid poll_rate value -5, defaulting to 1" in caplog.messages
+
+        # Test with poll_rate = 3
+        caplog.clear()
+        self.standart_options = StandardOptions()
+        test_res_data = {"plugin": {"python": {"poll_rate": 3}}}
+        self.standart_options.set_from(test_res_data)
+        assert self.standart_options.poll_rate == 1
+        assert "Invalid poll_rate value 3, defaulting to 1" in caplog.messages
+
+    def test_set_from_with_invalid_poll_rate_type(
+        self,
+        caplog: pytest.LogCaptureFixture,
+    ) -> None:
+        """Test that non-integer poll_rate values default to 1"""
+        caplog.set_level(logging.DEBUG, logger="instana")
+
+        # Test with string
+        caplog.clear()
+        self.standart_options = StandardOptions()
+        test_res_data = {"plugin": {"python": {"poll_rate": "invalid"}}}
+        self.standart_options.set_from(test_res_data)
+        assert self.standart_options.poll_rate == 1
+        assert "Invalid poll_rate type, defaulting to 1" in caplog.messages
+
+        # Test with None
+        caplog.clear()
+        self.standart_options = StandardOptions()
+        test_res_data = {"plugin": {"python": {"poll_rate": None}}}
+        self.standart_options.set_from(test_res_data)
+        assert self.standart_options.poll_rate == 1
+
+    def test_set_from_without_poll_rate(self) -> None:
+        """Test that poll_rate remains default when not in response"""
+        self.standart_options = StandardOptions()
+        test_res_data = {
+            "secrets": {"matcher": "sample-match", "list": ["sample", "list"]}
+        }
+        self.standart_options.set_from(test_res_data)
+        assert self.standart_options.poll_rate == 1
+
+    def test_set_from_with_poll_rate_and_other_config(
+        self,
+        caplog: pytest.LogCaptureFixture,
+    ) -> None:
+        """Test that poll_rate works alongside other configuration"""
+        caplog.set_level(logging.DEBUG, logger="instana")
+        caplog.clear()
+
+        self.standart_options = StandardOptions()
+        test_res_data = {
+            "plugin": {"python": {"poll_rate": 5}},
+            "secrets": {"matcher": "sample-match", "list": ["sample", "list"]},
+            "tracing": {
+                "filter": {
+                    "exclude": [
+                        {
+                            "name": "service1",
+                            "attributes": [
+                                {
+                                    "key": "service",
+                                    "values": ["service1"],
+                                    "match_type": "strict",
+                                }
+                            ],
+                        }
+                    ]
+                }
+            },
+        }
+        self.standart_options.set_from(test_res_data)
+
+        assert self.standart_options.poll_rate == 5
+        assert self.standart_options.secrets_matcher == "sample-match"
+        assert self.standart_options.secrets_list == ["sample", "list"]
+        assert "Poll rate set to 5 seconds from agent configuration" in caplog.messages
+
 
 class TestServerlessOptions:
     @pytest.fixture(autouse=True)