gerrit(lib): add cached marker to version section

We want to know how stale the cache is for of gerrit version check. By
adding the UNIX timestamp and TTL value to the section header via the
cached marker, we get this in the GUI out-of-the-box.

CMK-34901

Change-Id: I722a121164c638f08c6970790161cd82a1d21529

Author: logan-connolly

.werks/20252.md

@@ -0,0 +1,25 @@
+[//]: # (werk v3)
+# Gerrit: show cache age for version check
+
+key        | value
+---------- | ---
+date       | 2026-08-06T14:55:51.043709+00:00
+version    | 2.5.0p12
+class      | feature
+edition    | community
+component  | checks
+level      | 1
+compatible | yes
+
+The Gerrit version check caches its API call to reduce load on the monitored
+instance (see werk #17594), but there was no way to tell how stale a cached
+result was.
+
+The special agent now embeds the cache timestamp and TTL into the
+`gerrit_version` section header. Checkmk's core picks this up automatically,
+so the service now shows cache age information ("Cache generated X ago",
+cache interval, elapsed cache lifespan) in the GUI without any further
+configuration.
+
+There is nothing for the user to do; this information is shown automatically
+once the site is updated.

cmk/plugins/gerrit/lib/agent.py

@@ -12,6 +12,7 @@
 import json
 import sys
 from collections.abc import Sequence
+from typing import NewType
 
 from cmk.password_store.v1_unstable import parser_add_secret_option, resolve_secret_option
 from cmk.plugins.gerrit.lib.cache import cache_ttl
@@ -35,7 +36,7 @@ def main() -> int:
 
     ctx = GerritRunContext(
         hostname=args.hostname,
-        ttl=TTLCache(version=args.version_cache),
+        ttl=TTLCache(version=int(args.version_cache)),
         collectors=Collectors(version=GerritVersion(api_url=api_url, auth=auth)),
     )
 
@@ -106,18 +107,34 @@ class GerritRunContext:
 
 
 def run(ctx: GerritRunContext) -> int:
-    version_storage = Storage(f"{AGENT}_version", ctx.hostname)
-    version_cache = cache_ttl(version_storage, ttl=ctx.ttl.version)
-    collect_version = version_cache(ctx.collectors.version.collect)
-    _write_section(collect_version(), name="gerrit_version")
+    process_version_section(ctx)
 
     return 0
 
 
-def _write_section(data: object, *, name: str) -> None:
-    section_payload = json.dumps(data, sort_keys=True)
-    sys.stdout.write(f"<<<{name}:sep(0)>>>\n")
-    sys.stdout.write(f"{section_payload}\n")
+def process_version_section(ctx: GerritRunContext) -> None:
+    name = "gerrit_version"
+    storage = Storage(name, ctx.hostname)
+    cache_wrapper = cache_ttl(storage, ttl=ctx.ttl.version)
+    data, ts = cache_wrapper(ctx.collectors.version.collect)()
+    cache_marker = build_cache_marker(ts=ts, ttl=ctx.ttl.version) if ts is not None else None
+    write_section(data, name=name, cache_marker=cache_marker)
+
+
+Marker = NewType("Marker", str)
+"""Marker indicates that a string is prefixed with a colon and can be added to a section header."""
+
+
+def build_cache_marker(ts: float, ttl: int) -> Marker:
+    return Marker(f":cached({int(ts)},{ttl})")
+
+
+def write_section(data: object, *, name: str, cache_marker: Marker | None = None) -> None:
+    header = f"{name}:sep(0){cache_marker or ''}"
+    content = json.dumps(data, sort_keys=True)
+
+    sys.stdout.write(f"<<<{header}>>>\n")
+    sys.stdout.write(f"{content}\n")
 
 
 if __name__ == "__main__":

cmk/plugins/gerrit/lib/cache.py

@@ -15,18 +15,20 @@
 _HASH_NAMESPACE: Final = uuid.UUID("5871b8db-dcef-4c22-9b36-e81d7d4d66bb")
 
 
-def cache_ttl[**P, R](store: Storage, *, ttl: int) -> Callable[[Callable[P, R]], Callable[P, R]]:
+def cache_ttl[**P, R](
+    store: Storage, *, ttl: int
+) -> Callable[[Callable[P, R]], Callable[P, tuple[R, float | None]]]:
     if ttl < 0:
         raise ValueError("Time to live value must be a positive integer.")
 
     class Cache[T](TypedDict):
         ts: float
         data: T
 
-    def decorator(f: Callable[P, R]) -> Callable[P, R]:
-        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+    def decorator(f: Callable[P, R]) -> Callable[P, tuple[R, float | None]]:
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> tuple[R, float | None]:
             if ttl == 0:
-                return f(*args, **kwargs)
+                return f(*args, **kwargs), None
 
             if any(not isinstance(arg, Hashable) for arg in args):
                 raise ValueError(f"Unhashable arg values: {args}")
@@ -41,13 +43,13 @@ def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
                 cache = Cache[R](ts=raw_cache["ts"], data=raw_cache["data"])
 
                 if 0 < time.time() - cache["ts"] < ttl:
-                    return cache["data"]
+                    return cache["data"], cache["ts"]
 
             new_data = f(*args, **kwargs)
-            new_cache = Cache[R](ts=time.time(), data=new_data)
+            new_cache = Cache[R](ts=(ts := time.time()), data=new_data)
             store.write(key, json.dumps(new_cache))
 
-            return new_data
+            return new_data, ts
 
         return wrapper
 

tests/unit/cmk/plugins/gerrit/lib/test_agent.py

@@ -4,6 +4,7 @@
 # conditions defined in the file COPYING, which is part of this source code package.
 
 import argparse
+import re
 from pathlib import Path
 
 import pytest
@@ -31,8 +32,8 @@ def test_run_agent(capsys: pytest.CaptureFixture[str]) -> None:
     # agent ran without error
     assert captured.err == ""
 
-    # sections headings were successfully written out.
-    assert "<<<gerrit_version:sep(0)>>>" in captured.out
+    # section heading was written out with a cache timestamp.
+    assert re.search(r"<<<gerrit_version:sep\(0\):cached\([\d.]+,60\)>>>", captured.out)
 
     # cache is being used on second run.
     agent.run(ctx)
@@ -52,6 +53,11 @@ def test_run_agent_with_no_cache(capsys: pytest.CaptureFixture[str]) -> None:
     agent.run(ctx)
     second_run_output = capsys.readouterr().out
 
+    # section heading should not have :cached marker
+    assert "<<<gerrit_version:sep(0)>>>" in first_run_output
+    assert "<<<gerrit_version:sep(0)>>>" in second_run_output
+
+    # data should be different between runs
     assert first_run_output != second_run_output