Support explicit metric timestamps

Author: q

README.md

@@ -103,6 +103,12 @@ client.rate("sensor.samples_per_second", 2.0)
 client.flush()
 ```
 
+Pass `timestamp=` to use an explicit Unix timestamp instead of `time.time()`:
+
+```python
+client.gauge("sensor.temperature", 23.8, timestamp=1710000123)
+```
+
 `flush()` returns `True` when Datadog accepts the payload with a 2xx HTTP status.
 It returns `False` on network errors, socket errors, HTTP error status codes, or
 unexpected request failures. It never intentionally raises an exception, and it

datadog.py

@@ -49,17 +49,17 @@ def __init__(
             "Content-Type": "application/json",
         }
 
-    def gauge(self, metric, value, tags=None):
+    def gauge(self, metric, value, tags=None, timestamp=None):
         """Buffer a gauge metric."""
-        self._add_metric(metric, value, _TYPE_GAUGE, tags)
+        self._add_metric(metric, value, _TYPE_GAUGE, tags, timestamp)
 
-    def count(self, metric, value, tags=None):
+    def count(self, metric, value, tags=None, timestamp=None):
         """Buffer a count metric."""
-        self._add_metric(metric, value, _TYPE_COUNT, tags)
+        self._add_metric(metric, value, _TYPE_COUNT, tags, timestamp)
 
-    def rate(self, metric, value, tags=None):
+    def rate(self, metric, value, tags=None, timestamp=None):
         """Buffer a rate metric."""
-        self._add_metric(metric, value, _TYPE_RATE, tags)
+        self._add_metric(metric, value, _TYPE_RATE, tags, timestamp)
 
     def flush(self):
         """Send buffered metrics.
@@ -111,9 +111,12 @@ def flush(self):
         self._buffer = []
         return False
 
-    def _add_metric(self, metric, value, metric_type, tags):
+    def _add_metric(self, metric, value, metric_type, tags, timestamp):
+        if timestamp is None:
+            timestamp = time.time()
+
         point = {
-            "timestamp": int(time.time()),
+            "timestamp": int(timestamp),
             "value": value,
         }
         item = {

tests/test_datadog.py

@@ -88,6 +88,20 @@ def test_builds_metric_payloads_with_types_and_tags(self):
         self.assertEqual(series[2]["type"], 2)
         self.assertEqual(series[2]["tags"], ["env:test"])
 
+    def test_accepts_explicit_metric_timestamps(self):
+        session = FakeSession([202])
+        client = datadog.DatadogClient(session, "api-key")
+
+        client.gauge("sensor.temperature", 22.5, timestamp=1710000123)
+        client.count("button.press", 1, timestamp=1710000124)
+        client.rate("sensor.samples_per_second", 2.0, timestamp=1710000125)
+
+        self.assertTrue(client.flush())
+        series = session.posts[0]["json"]["series"]
+        self.assertEqual(series[0]["points"][0]["timestamp"], 1710000123)
+        self.assertEqual(series[1]["points"][0]["timestamp"], 1710000124)
+        self.assertEqual(series[2]["points"][0]["timestamp"], 1710000125)
+
     def test_constructs_datadog_site_urls(self):
         cases = (
             ("datadoghq.com", "https://api.datadoghq.com/api/v2/series"),