feat(runtime): Update pollrate behavior and add tests for it

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

Author: CagriYonca

src/instana/collector/helpers/runtime.py

@@ -44,10 +44,11 @@ def __init__(
         self.previous = DictionaryOfStan()
         self.previous_rusage = get_resource_usage()
 
-        if gc.isenabled():
-            self.previous_gc_count = gc.get_count()
-        else:
-            self.previous_gc_count = None
+        # Initialise to None so the first collect_metrics call establishes the
+        # baseline snapshot and reports all-zero deltas.  Any GC activity that
+        # occurs between process start and the first collection is intentionally
+        # excluded — we only report incremental deltas from the first poll onward.
+        self.previous_gc_stats = None
 
     def collect_metrics(self, **kwargs: Dict[str, Any]) -> List[Dict[str, Any]]:
         plugin_data = dict()
@@ -232,52 +233,27 @@ def _collect_runtime_metrics(
 
     def _collect_gc_metrics(self, plugin_data, with_snapshot):
         try:
-            gc_count = gc.get_count()
-            gc_threshold = gc.get_threshold()
-
-            self.apply_delta(
-                gc_count[0],
-                self.previous["data"]["metrics"]["gc"],
-                plugin_data["data"]["metrics"]["gc"],
-                "collect0",
-                with_snapshot,
-            )
-            self.apply_delta(
-                gc_count[1],
-                self.previous["data"]["metrics"]["gc"],
-                plugin_data["data"]["metrics"]["gc"],
-                "collect1",
-                with_snapshot,
-            )
-            self.apply_delta(
-                gc_count[2],
-                self.previous["data"]["metrics"]["gc"],
-                plugin_data["data"]["metrics"]["gc"],
-                "collect2",
-                with_snapshot,
-            )
-
-            self.apply_delta(
-                gc_threshold[0],
-                self.previous["data"]["metrics"]["gc"],
-                plugin_data["data"]["metrics"]["gc"],
-                "threshold0",
-                with_snapshot,
-            )
-            self.apply_delta(
-                gc_threshold[1],
-                self.previous["data"]["metrics"]["gc"],
-                plugin_data["data"]["metrics"]["gc"],
-                "threshold1",
-                with_snapshot,
-            )
-            self.apply_delta(
-                gc_threshold[2],
-                self.previous["data"]["metrics"]["gc"],
-                plugin_data["data"]["metrics"]["gc"],
-                "threshold2",
-                with_snapshot,
-            )
+            gc_stats = gc.get_stats()
+            if self.previous_gc_stats is None:
+                # First call: establish baseline, report all-zero deltas so the
+                # snapshot payload carries zeros rather than the cumulative counts
+                # that accumulated since process start (which are not meaningful
+                # as deltas).
+                self.previous_gc_stats = gc_stats
+                return
+
+            # Use a plain dict as the staging target so that accessing it never
+            # auto-creates keys in plugin_data (DictionaryOfStan creates keys on
+            # read, which would leave an empty "gc": {} even when nothing changed).
+            staging = {}
+            prev_gc = self.previous["data"]["metrics"]["gc"]
+            for i, (stat, prev_stat) in enumerate(zip(gc_stats, self.previous_gc_stats)):
+                for key in ("collections", "collected", "uncollectable"):
+                    delta = stat[key] - prev_stat.get(key, 0)
+                    self.apply_delta(delta, prev_gc, staging, f"{key}{i}", with_snapshot)
+            if staging:
+                plugin_data["data"]["metrics"]["gc"].update(staging)
+            self.previous_gc_stats = gc_stats
         except Exception:
             logger.debug("_collect_gc_metrics", exc_info=True)
 
@@ -333,6 +309,21 @@ def _collect_runtime_snapshot(
             snapshot_payload["versions"] = self.gather_python_packages()
             snapshot_payload["iv"] = VERSION
 
+            # Inform filler of the configured poll_rate so that entity expiry is
+            # scaled correctly (presenceExpirySeconds = 20 * poll_rate).
+            # The backend reads this via SnapshotExtracting.describePollRateSnapshot()
+            # which looks for the top-level "pollRate" key in the payload.
+            poll_rate = getattr(
+                getattr(self.collector, "agent", None),
+                "options",
+                None,
+            )
+            if poll_rate is not None:
+                poll_rate = getattr(poll_rate, "poll_rate", 1)
+            else:
+                poll_rate = 1
+            plugin_data["data"]["pollRate"] = poll_rate
+
             if is_autowrapt_instrumented():
                 snapshot_payload["m"] = "Autowrapt"
             elif is_webhook_instrumented():

src/instana/options.py

@@ -360,7 +360,7 @@ class StandardOptions(BaseOptions):
     AGENT_DEFAULT_HOST = "localhost"
     AGENT_DEFAULT_PORT = 42699
     DEFAULT_POLL_RATE = 1
-    MAX_POLL_RATE = 5
+    VALID_POLL_RATES = [1, 5, 10, 20, 30, 60, 120, 180, 240, 300, 360, 420, 480, 540, 600]
 
     def __init__(self, **kwds: dict[str, Any]) -> None:
         super(StandardOptions, self).__init__()
@@ -543,7 +543,11 @@ def set_disable_tracing(self, tracing_config: Sequence[dict[str, Any]]) -> None:
             self.enabled_spans.extend(enabled_spans)
 
     def set_poll_rate(self, plugin_config: dict[str, Any]) -> None:
-        """Set poll rate from agent plugin configuration."""
+        """Set poll rate from agent plugin configuration.
+
+        Normalizes the received value to the nearest valid poll rate in
+        VALID_POLL_RATES, matching the behaviour of Java PollRateUtil.
+        """
         poll_rate_value = plugin_config.get("poll_rate")
         if poll_rate_value is None:
             return
@@ -557,18 +561,17 @@ def set_poll_rate(self, plugin_config: dict[str, Any]) -> None:
             self.poll_rate = self.DEFAULT_POLL_RATE
             return
 
-        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"
+        if poll_rate <= 0:
+            self.poll_rate = self.DEFAULT_POLL_RATE
+            logger.warning(
+                f"Invalid poll_rate value {poll_rate}, defaulting to {self.DEFAULT_POLL_RATE}"
             )
             return
 
+        self.poll_rate = min(self.VALID_POLL_RATES, key=lambda x: abs(x - poll_rate))
         logger.debug(
-            f"Invalid poll_rate value {poll_rate}, defaulting to "
-            f"{self.DEFAULT_POLL_RATE}"
+            f"Poll rate set to {self.poll_rate} seconds from agent configuration"
         )
-        self.poll_rate = self.DEFAULT_POLL_RATE
 
     def set_from(self, res_data: dict[str, Any]) -> None:
         """

tests/collector/helpers/test_collector_runtime.py

@@ -38,7 +38,8 @@ def test_collect_runtime_snapshot_default(self) -> None:
         self.helper._collect_runtime_snapshot(plugin_data[0])
         assert plugin_data[0]["name"] == "com.instana.plugin.python"
         assert plugin_data[0]["data"]["snapshot"]["m"] == "Manual"
-        assert len(plugin_data[0]["data"]) == 3
+        # data contains: pid, metrics, pollRate, snapshot
+        assert len(plugin_data[0]["data"]) == 4
 
     def test_collect_runtime_snapshot_autowrapt(self) -> None:
         with patch(
@@ -49,7 +50,8 @@ def test_collect_runtime_snapshot_autowrapt(self) -> None:
             self.helper._collect_runtime_snapshot(plugin_data[0])
             assert plugin_data[0]["name"] == "com.instana.plugin.python"
             assert plugin_data[0]["data"]["snapshot"]["m"] == "Autowrapt"
-            assert len(plugin_data[0]["data"]) == 3
+            # data contains: pid, metrics, pollRate, snapshot
+            assert len(plugin_data[0]["data"]) == 4
 
     def test_collect_runtime_snapshot_webhook(self) -> None:
         with patch(
@@ -60,7 +62,8 @@ def test_collect_runtime_snapshot_webhook(self) -> None:
             self.helper._collect_runtime_snapshot(plugin_data[0])
             assert plugin_data[0]["name"] == "com.instana.plugin.python"
             assert plugin_data[0]["data"]["snapshot"]["m"] == "AutoTrace"
-            assert len(plugin_data[0]["data"]) == 3
+            # data contains: pid, metrics, pollRate, snapshot
+            assert len(plugin_data[0]["data"]) == 4
 
     def test_collect_gc_metrics(self) -> None:
         plugin_data = self.helper.collect_metrics()
@@ -174,6 +177,44 @@ def test_collect_runtime_metrics_with_resource_usage(self, mocker):
         # Verify the previous_rusage was updated
         assert self.helper.previous_rusage == new_resource
 
+    def test_collect_runtime_snapshot_poll_rate_default(self) -> None:
+        """pollRate defaults to 1 when agent has no options configured."""
+        plugin_data = self.helper.collect_metrics()
+        self.helper._collect_runtime_snapshot(plugin_data[0])
+        assert plugin_data[0]["data"]["pollRate"] == 1
+
+    def test_collect_runtime_snapshot_poll_rate_from_agent_options(self) -> None:
+        """pollRate is read from agent.options.poll_rate and written to data top-level."""
+        self.helper.collector.agent.options.poll_rate = 60
+        plugin_data = self.helper.collect_metrics()
+        self.helper._collect_runtime_snapshot(plugin_data[0])
+        assert plugin_data[0]["data"]["pollRate"] == 60
+
+    def test_collect_runtime_snapshot_poll_rate_no_options(self) -> None:
+        """pollRate defaults to 1 when agent has no options attribute."""
+        self.helper.collector.agent.options = None
+        plugin_data = self.helper.collect_metrics()
+        self.helper._collect_runtime_snapshot(plugin_data[0])
+        assert plugin_data[0]["data"]["pollRate"] == 1
+
+    def test_collect_runtime_snapshot_poll_rate_no_agent(self) -> None:
+        """pollRate defaults to 1 when collector has no agent attribute."""
+        self.helper.collector.agent = None
+        plugin_data = self.helper.collect_metrics()
+        self.helper._collect_runtime_snapshot(plugin_data[0])
+        assert plugin_data[0]["data"]["pollRate"] == 1
+
+    def test_collect_runtime_snapshot_poll_rate_at_top_level_not_in_snapshot(self) -> None:
+        """pollRate must be at data top-level, not nested inside snapshot.
+        Backend's PollRateUtil.regularPollRateFromPayload() reads payload.getByPath("pollRate")
+        which is a flat lookup on the data map — it cannot find a nested key.
+        """
+        self.helper.collector.agent.options.poll_rate = 30
+        plugin_data = self.helper.collect_metrics()
+        self.helper._collect_runtime_snapshot(plugin_data[0])
+        assert plugin_data[0]["data"]["pollRate"] == 30
+        assert "pollRate" not in plugin_data[0]["data"].get("snapshot", {})
+
     @patch("os.environ")
     def test_collect_runtime_metrics_disabled(self, mock_environ):
         """Test that _collect_runtime_metrics respects INSTANA_DISABLE_METRICS_COLLECTION"""

tests/test_options.py

@@ -2,7 +2,8 @@
 
 import logging
 import os
-from typing import Generator, Optional
+from collections.abc import Generator
+from typing import Optional
 
 import pytest
 from mock import patch
@@ -1093,14 +1094,14 @@ def test_default_poll_rate(self) -> None:
 
     @pytest.mark.parametrize(
         "poll_rate_value",
-        [1, 5],
+        [1, 5, 10, 60, 600],
     )
     def test_set_from_with_valid_poll_rate(
         self,
         poll_rate_value: int,
         caplog: pytest.LogCaptureFixture,
     ) -> None:
-        """Test setting poll_rate from announce response - affects metrics only"""
+        """Test setting poll_rate from announce response — exact valid values are accepted as-is."""
         caplog.set_level(logging.DEBUG, logger="instana")
         caplog.clear()
 
@@ -1115,27 +1116,60 @@ def test_set_from_with_valid_poll_rate(
         )
 
     @pytest.mark.parametrize(
-        "invalid_value",
-        [10, 0, -5, 3],
+        "invalid_value,expected",
+        [
+            (0, 1),   # zero → default
+            (-5, 1),  # negative → default
+        ],
     )
     def test_set_from_with_invalid_poll_rate_defaults_to_1(
         self,
         invalid_value: int,
+        expected: int,
         caplog: pytest.LogCaptureFixture,
     ) -> None:
-        """Test that invalid poll_rate values default to 1"""
+        """Test that zero and negative poll_rate values default to 1."""
         caplog.set_level(logging.DEBUG, logger="instana")
         caplog.clear()
 
         self.standart_options = StandardOptions()
         test_res_data = {"plugin": {"python": {"poll_rate": invalid_value}}}
         self.standart_options.set_from(test_res_data)
-        assert self.standart_options.poll_rate == 1
+        assert self.standart_options.poll_rate == expected
         assert (
             f"Invalid poll_rate value {invalid_value}, defaulting to 1"
             in caplog.messages
         )
 
+    @pytest.mark.parametrize(
+        "input_value,expected",
+        [
+            (3, 1),  # nearest to 1
+            (7, 5),  # nearest to 5 (|7-5|=2 < |7-10|=3)
+            (8, 10),  # nearest to 10
+            (100, 120),  # nearest to 120 (|100-60|=40 > |100-120|=20)
+            (700, 600),  # above max → clamp to 600
+        ],
+    )
+    def test_set_from_with_non_exact_poll_rate_rounds_to_nearest(
+        self,
+        input_value: int,
+        expected: int,
+        caplog: pytest.LogCaptureFixture,
+    ) -> None:
+        """Test that non-exact values are rounded to the nearest valid poll rate."""
+        caplog.set_level(logging.DEBUG, logger="instana")
+        caplog.clear()
+
+        self.standart_options = StandardOptions()
+        test_res_data = {"plugin": {"python": {"poll_rate": input_value}}}
+        self.standart_options.set_from(test_res_data)
+        assert self.standart_options.poll_rate == expected
+        assert (
+            f"Poll rate set to {expected} seconds from agent configuration"
+            in caplog.messages
+        )
+
     @pytest.mark.parametrize(
         "invalid_type,expect_log",
         [