fix(api): stamp emissions with measurement time, not send time

ApiClient.add_emission discarded carbon_emission["timestamp"] and called
get_datetime_with_timezone() instead, so every row stored the moment the
payload was built rather than the moment it was measured. Harmless while
the two are milliseconds apart; wrong by the full latency as soon as a
send is slow, retried or queued.

Normalise the measurement timestamp to offset-aware instead, falling back
to now when the payload carries none or an unparseable one (the method is
public and takes a plain dict). CSV output is untouched.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: davidberenstein1957

codecarbon/core/api_client.py

@@ -8,7 +8,7 @@
 # from httpx import AsyncClient
 import dataclasses
 import json
-from datetime import timedelta, tzinfo
+from datetime import datetime, timedelta, tzinfo
 
 import requests
 
@@ -33,12 +33,26 @@ def get_datetime_with_timezone():
     return str(arrow.now().isoformat())
 
 
-# (connect, read) seconds. The old flat 2s timed out on a healthy but
-# loaded API; these leave room without letting a hung endpoint block the
-# scheduler thread for long.
+# (connect, read) seconds, replacing a flat 2s that timed out on a loaded API.
 _TIMEOUT = (3.05, 10)
 
 
+def _measurement_timestamp(carbon_emission: dict) -> str:
+    """
+    Offset-aware ISO timestamp of *when the measurement was taken*, taken from
+    EmissionsData.timestamp. Falls back to now for hand-built payloads that
+    carry no usable timestamp.
+    """
+    try:
+        return (
+            datetime.fromisoformat(carbon_emission["timestamp"])
+            .astimezone()
+            .isoformat()
+        )
+    except (KeyError, TypeError, ValueError):
+        return get_datetime_with_timezone()
+
+
 class ApiClient:  # (AsyncClient)
     """
     This class call the Code Carbon API
@@ -64,9 +78,7 @@ def __init__(
         :create_run_automatically: If False, do not create a run. To use API in read only mode.
         """
         # super().__init__(base_url=endpoint_url) # (AsyncClient)
-        # A Session so the socket and TLS handshake are reused across calls:
-        # a tracker sending one measurement per tick otherwise opens a new
-        # connection every time.
+        # A Session so the socket and TLS handshake are reused across calls.
         self._session = requests.Session()
         self.url = endpoint_url
         self.experiment_id = experiment_id
@@ -209,7 +221,7 @@ def add_emission(self, carbon_emission: dict):
             )
             return False
         emission = EmissionCreate(
-            timestamp=get_datetime_with_timezone(),
+            timestamp=_measurement_timestamp(carbon_emission),
             run_id=self.run_id,
             duration=int(carbon_emission["duration"]),
             emissions_sum=carbon_emission["emissions"],

codecarbon/output_methods/http.py

@@ -58,8 +58,6 @@ def __init__(
         self.run_id = self.api.run_id
 
     def exit(self) -> None:
-        # A Session holds sockets; long-lived processes creating many trackers
-        # would otherwise leak file descriptors.
         self.api.close()
 
     def _ensure_api_run(self) -> None:

tests/test_api_call.py

@@ -1,5 +1,6 @@
 import dataclasses
 import unittest
+from datetime import datetime
 from uuid import uuid4
 
 import requests
@@ -261,6 +262,45 @@ def test_add_emission_skips_short_duration(self):
             )
         )
 
+    def test_add_emission_keeps_measurement_timestamp(self):
+        """The row must carry when it was measured, not when it was sent."""
+        payload = {
+            "duration": 10,
+            "emissions": 1.0,
+            "emissions_rate": 1.0,
+            "cpu_power": 1.0,
+            "gpu_power": 0.0,
+            "ram_power": 0.5,
+            "cpu_energy": 0.1,
+            "gpu_energy": 0.0,
+            "ram_energy": 0.1,
+            "energy_consumed": 0.2,
+        }
+        with requests_mock.Mocker() as m:
+            m.post("http://test.com/emissions", status_code=201)
+            api = ApiClient(
+                endpoint_url="http://test.com",
+                experiment_id="exp-1",
+                conf=conf,
+                create_run_automatically=False,
+            )
+            api.run_id = "run-1"
+
+            # naive timestamp, as produced by EmissionsData
+            assert api.add_emission({**payload, "timestamp": "2020-01-01T00:00:00"})
+            sent = datetime.fromisoformat(m.last_request.json()["timestamp"])
+            self.assertEqual(
+                sent.replace(tzinfo=None).isoformat(), "2020-01-01T00:00:00"
+            )
+            self.assertIsNotNone(sent.tzinfo)
+
+            # missing / unparseable timestamps fall back to now
+            for bad in ({}, {"timestamp": None}, {"timestamp": "222"}):
+                assert api.add_emission({**payload, **bad})
+                sent = datetime.fromisoformat(m.last_request.json()["timestamp"])
+                self.assertIsNotNone(sent.tzinfo)
+                self.assertGreater(sent.year, 2020)
+
     def test_add_emission_raises_on_unsuccessful_post(self):
         with requests_mock.Mocker() as m:
             m.post("http://test.com/emissions", text="bad", status_code=500)