k8stools 2.2.0__tar.gz → 2.2.1__tar.gz

{k8stools-2.2.0 → k8stools-2.2.1}/CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to k8stools. Versions follow [semantic versioning](https://semver.org/);
 dates are release-tag dates.
 
+## 2.2.1 — 2026-09-29
+
+### Documentation
+- **Event records can lag behind what they count** (follow-up to issue #8). The
+  kubelet counts every occurrence but, by default, writes at most one update per
+  object and event type every 5 minutes once a burst of 25 is used up (client-go's
+  event spam filter). A crash-looping pod's `Created` record read `last_seen`
+  29 minutes while the container had restarted 46 seconds earlier, then its count
+  jumped by six in one update. The `get_pod_events` and `get_events` descriptions
+  now say so: `count / (first_seen - last_seen)` still gives the rate, since both
+  lag together, but `last_seen` is not the time of the last restart (use the
+  container status or `PodSummary.last_restart`), and counts for different reasons
+  can differ by a few for the same restarts.
+- `PodSummary.last_restart` is described as what it is: time since a container
+  last *terminated*. For a container waiting in CrashLoopBackOff, that is its last
+  crash, not a restart.
+
 ## 2.2.0 — 2026-09-28
 
 ### Added

{k8stools-2.2.0 → k8stools-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: k8stools
-Version: 2.2.0
+Version: 2.2.1
 Summary: Tools and an MCP server for building Kubernetes agents
 Project-URL: Homepage, https://github.com/BenedatLLC/k8stools
 Project-URL: Changelog, https://github.com/BenedatLLC/k8stools/blob/main/CHANGELOG.md

{k8stools-2.2.0 → k8stools-2.2.1}/pyproject.toml

@@ -1,7 +1,7 @@
 
 [project]
 name = "k8stools"
-version = "2.2.0"
+version = "2.2.1"
 description = "Tools and an MCP server for building Kubernetes agents"
 readme = "README.md"
 requires-python = ">=3.12"

{k8stools-2.2.0 → k8stools-2.2.1}/src/k8stools/__init__.py

@@ -78,4 +78,4 @@ the built-in OTel Demo snapshot by default, or your own via load_mock_state() or
 the server's --state-file option.
 """
 
-__version__ = "2.2.0"
+__version__ = "2.2.1"

{k8stools-2.2.0 → k8stools-2.2.1}/src/k8stools/k8s_tools.py

@@ -544,7 +544,11 @@ def get_pod_summaries(namespace: Optional[str] = None) -> list[PodSummary]:
         restarts : int
             Total number of restarts for all containers in the pod.
         last_restart : Optional[datetime.timedelta]
-            Time since the container last restart (None if never restarted).
+            Time since a container of this pod last terminated - the most
+            recent last_state.finished_at across its containers - or None if
+            none has. For a container waiting in CrashLoopBackOff this is its
+            last crash, not a restart: it has not been started again yet. Taken
+            from the kubelet's status, so it is current, unlike event records.
         age : datetime.timedelta
             Age of the pod (current time minus creation timestamp).
         ip : Optional[str]
@@ -739,6 +743,22 @@ def get_pod_events(pod_name: str, namespace: str = "default") -> list[EventSumma
             kubelet waits to restart, so its count is several times the number
             of restarts. count divided by (first_seen - last_seen) is the
             average rate over that window, not the current back-off.
+
+            A record can lag behind what it counts. By default the kubelet
+            writes at most one event update per object and event type
+            ("Normal" or "Warning") every 5 minutes, once a burst of 25 is
+            used up; occurrences in between are counted but only written with
+            the next update, which then jumps by several at once. So count and
+            last_seen describe the most recent *written* occurrence and can
+            trail reality by several occurrences and tens of minutes. They lag
+            together, so the rate above still holds, but last_seen is not the
+            time of the last restart: for that, use the container status
+            (last_state.finished_at, state.started_at from
+            get_pod_container_statuses) or PodSummary.last_restart, which come
+            from the kubelet's status rather than from events. "Pulled",
+            "Created" and "Started" share one write budget, so their counts for
+            the same restarts can differ by a few; don't compare counts across
+            reasons.
         type : str
             Type of the event.
         reason : str
@@ -2507,6 +2527,22 @@ def get_events(namespace: Optional[str] = None,
             kubelet waits to restart, so its count is several times the number
             of restarts. count divided by (first_seen - last_seen) is the
             average rate over that window, not the current back-off.
+
+            A record can lag behind what it counts. By default the kubelet
+            writes at most one event update per object and event type
+            ("Normal" or "Warning") every 5 minutes, once a burst of 25 is
+            used up; occurrences in between are counted but only written with
+            the next update, which then jumps by several at once. So count and
+            last_seen describe the most recent *written* occurrence and can
+            trail reality by several occurrences and tens of minutes. They lag
+            together, so the rate above still holds, but last_seen is not the
+            time of the last restart: for that, use the container status
+            (last_state.finished_at, state.started_at from
+            get_pod_container_statuses) or PodSummary.last_restart, which come
+            from the kubelet's status rather than from events. "Pulled",
+            "Created" and "Started" share one write budget, so their counts for
+            the same restarts can differ by a few; don't compare counts across
+            reasons.
         type : str
             Type of the event ("Normal" or "Warning").
         reason : str

{k8stools-2.2.0 → k8stools-2.2.1}/tests/test_events.py

@@ -126,6 +126,20 @@ def test_docstrings_warn_that_backoff_counts_are_not_restarts():
         assert "first_seen" in tool.__doc__ and "count" in tool.__doc__
 
 
+def test_docstrings_warn_that_records_lag_behind_what_they_count():
+    """client-go counts an occurrence before its spam filter decides whether to
+    write it, and the filter budgets writes per object and event type (burst 25,
+    then one per 5 minutes). On a real crash loop a Created record's last_seen
+    read 29 minutes while the container had restarted 46s earlier, then its
+    count jumped 595 -> 601. The docstring has to send agents to the container
+    status for the time of the last restart."""
+    for tool in (k8s_tools.get_pod_events, k8s_tools.get_events):
+        doc = tool.__doc__
+        assert "lag" in doc and "every 5 minutes" in doc
+        assert "last_state.finished_at" in doc and "PodSummary.last_restart" in doc
+        assert "don't compare counts across" in doc
+
+
 # --- capture and replay --------------------------------------------------------
 
 def _capture(events):

{k8stools-2.2.0 → k8stools-2.2.1}/uv.lock

@@ -544,7 +544,7 @@ wheels = [
 
 [[package]]
 name = "k8stools"
-version = "2.2.0"
+version = "2.2.1"
 source = { editable = "." }
 dependencies = [
     { name = "kubernetes" },