Document implications of negative observations

beorn7 · beorn7 · commit 13f786af7e5a · 2021-05-27T00:03:18.000+02:00
Fixes prometheus#638. It's of course weird to talk abou negative values of an "amount". However, for the Gauge, which quite regularly will receive negative increments, the word "amount" is used, too, so I didn't want to change it everywhere to "value" or something. AFAIK the only place where negative values are rejected is indeed the Counter. Signed-off-by: beorn7 <beorn@grafana.com>
diff --git a/prometheus_client/metrics.py b/prometheus_client/metrics.py
@@ -441,7 +441,15 @@ def _metric_init(self):
         self._created = time.time()
 
     def observe(self, amount):
-        """Observe the given amount."""
+        """Observe the given amount.
+
+        The amount is usually positive or zero. Negative values are
+        accepted but prevent current versions of Prometheus from
+        properly detecting counter resets in the sum of
+        observations. See
+        https://prometheus.io/docs/practices/histograms/#count-and-sum-of-observations
+        for details.
+        """
         self._count.inc(1)
         self._sum.inc(amount)
 
@@ -550,7 +558,15 @@ def _metric_init(self):
             )
 
     def observe(self, amount):
-        """Observe the given amount."""
+        """Observe the given amount.
+
+        The amount is usually positive or zero. Negative values are
+        accepted but prevent current versions of Prometheus from
+        properly detecting counter resets in the sum of
+        observations. See
+        https://prometheus.io/docs/practices/histograms/#count-and-sum-of-observations
+        for details.
+        """
         self._sum.inc(amount)
         for i, bound in enumerate(self._upper_bounds):
             if amount <= bound:
