Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(integrations): record metric timestamps in UTC, not naive local time (#3117)

Abhay Singh76ef2c3bc9cc
diff --git a/headroom/integrations/autogen/agents.py b/headroom/integrations/autogen/agents.py
index a83abbd1a..ca78375fc 100644
--- a/headroom/integrations/autogen/agents.py
+++ b/headroom/integrations/autogen/agents.py
@@ -36,7 +36,7 @@ import asyncio
import functools
import logging
from dataclasses import dataclass, field
-from datetime import datetime
+from datetime import datetime, timezone
from typing import Any
try:
@@ -226,7 +226,7 @@ def _record_metrics(
metric = ToolCompressionMetrics(
tool_name=tool_name,
- timestamp=datetime.now(),
+ timestamp=datetime.now(timezone.utc),
chars_before=chars_before,
chars_after=chars_after,
chars_saved=max(0, chars_saved),
diff --git a/headroom/integrations/crewai/agents.py b/headroom/integrations/crewai/agents.py
index e96de992a..6cb54870a 100644
--- a/headroom/integrations/crewai/agents.py
+++ b/headroom/integrations/crewai/agents.py
@@ -26,7 +26,7 @@ from __future__ import annotations
import logging
from dataclasses import dataclass, field
-from datetime import datetime
+from datetime import datetime, timezone
from typing import Any
try:
@@ -294,7 +294,7 @@ class HeadroomToolWrapper(BaseTool): # type: ignore[misc]
metric = ToolCompressionMetrics(
tool_name=self.name,
- timestamp=datetime.now(),
+ timestamp=datetime.now(timezone.utc),
chars_before=chars_before,
chars_after=chars_after,
chars_saved=max(0, chars_saved),
diff --git a/headroom/integrations/langchain/agents.py b/headroom/integrations/langchain/agents.py
index 26b1c0e35..1fb4dab52 100644
--- a/headroom/integrations/langchain/agents.py
+++ b/headroom/integrations/langchain/agents.py
@@ -25,7 +25,7 @@ from __future__ import annotations
import logging
from dataclasses import dataclass, field
-from datetime import datetime
+from datetime import datetime, timezone
from typing import Any
# LangChain imports - these are optional dependencies
@@ -289,7 +289,7 @@ class HeadroomToolWrapper:
metric = ToolCompressionMetrics(
tool_name=self.name,
- timestamp=datetime.now(),
+ timestamp=datetime.now(timezone.utc),
chars_before=chars_before,
chars_after=chars_after,
chars_saved=max(0, chars_saved),
diff --git a/headroom/integrations/langchain/chat_model.py b/headroom/integrations/langchain/chat_model.py
index b9b51452c..871f6b44f 100644
--- a/headroom/integrations/langchain/chat_model.py
+++ b/headroom/integrations/langchain/chat_model.py
@@ -33,7 +33,7 @@ import json
import logging
from collections.abc import AsyncIterator, Iterator, Sequence
from dataclasses import dataclass
-from datetime import datetime
+from datetime import datetime, timezone
from typing import Any
from uuid import UUID, uuid4
@@ -350,7 +350,7 @@ class HeadroomChatModel(BaseChatModel):
# Create metrics
metrics = OptimizationMetrics(
request_id=request_id,
- timestamp=datetime.now(),
+ timestamp=datetime.now(timezone.utc),
tokens_before=result.tokens_before,
tokens_after=result.tokens_after,
tokens_saved=result.tokens_before - result.tokens_after,
@@ -920,7 +920,7 @@ class HeadroomRunnable:
# Track metrics
metrics = OptimizationMetrics(
request_id=str(uuid4()),
- timestamp=datetime.now(),
+ timestamp=datetime.now(timezone.utc),
tokens_before=result.tokens_before,
tokens_after=result.tokens_after,
tokens_saved=result.tokens_before - result.tokens_after,
diff --git a/headroom/integrations/langchain/langsmith.py b/headroom/integrations/langchain/langsmith.py
index 6dfb4930f..f7bd14359 100644
--- a/headroom/integrations/langchain/langsmith.py
+++ b/headroom/integrations/langchain/langsmith.py
@@ -39,7 +39,7 @@ from __future__ import annotations
import logging
import os
from dataclasses import dataclass, field
-from datetime import datetime
+from datetime import datetime, timezone
from typing import Any
from uuid import UUID
@@ -86,7 +86,7 @@ class PendingMetrics:
tokens_saved: int
savings_percent: float
transforms_applied: list[str]
- timestamp: datetime = field(default_factory=datetime.now)
+ timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
class HeadroomLangSmithCallbackHandler(BaseCallbackHandler):
diff --git a/tests/test_integration_metric_timestamps_utc.py b/tests/test_integration_metric_timestamps_utc.py
new file mode 100644
index 000000000..a8ea6f9bb
--- /dev/null
+++ b/tests/test_integration_metric_timestamps_utc.py
@@ -0,0 +1,103 @@
+"""Integration metric timestamps must be recorded in UTC, not local time.
+
+The SDK's canonical recorder (`headroom/client.py`) and the agno/strands
+adapters stamp metric timestamps in UTC, and `langchain/langsmith.py` exports a
+metric timestamp via `.isoformat()` as the absolute `headroom.optimization_timestamp`
+telemetry field. The autogen/crewai/langchain tool wrappers, and the langsmith
+`PendingMetrics` default, used a naive local `datetime.now()`, which records the
+local wall-clock time with no offset — read downstream as UTC, it is wrong by the
+local UTC offset for every non-UTC user.
+
+These adapters import their frameworks lazily, so the recording and serialization
+seams are exercised directly here without installing autogen/crewai/langchain.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from types import SimpleNamespace
+
+from headroom.integrations.autogen.agents import ToolMetricsCollector as AutogenCollector
+from headroom.integrations.autogen.agents import _record_metrics as autogen_record
+from headroom.integrations.crewai.agents import HeadroomToolWrapper as CrewaiWrapper
+from headroom.integrations.crewai.agents import ToolMetricsCollector as CrewaiCollector
+from headroom.integrations.langchain.agents import HeadroomToolWrapper as LangchainWrapper
+from headroom.integrations.langchain.agents import ToolMetricsCollector as LangchainCollector
+
+
+def _assert_utc(ts: object) -> None:
+ assert isinstance(ts, datetime)
+ # Aware and anchored to UTC (naive local time would have tzinfo is None).
+ assert ts.tzinfo is not None
+ assert ts.utcoffset() == timedelta(0)
+ # Serialization contract: langchain/langsmith exports this value verbatim via
+ # ``metrics.timestamp.isoformat()``, so the persisted string must carry an
+ # explicit UTC offset — otherwise a downstream reader silently treats it as
+ # local time. A naive datetime serializes with no offset at all, and an aware
+ # ``isoformat()`` yields a valid ``+00:00`` string (never the malformed
+ # ``+00:00Z`` that appending "Z" to an aware datetime would produce). This
+ # path does not go through ``headroom.utils.format_timestamp``, so it is
+ # correct independently of that helper.
+ serialized = ts.isoformat()
+ assert serialized.endswith("+00:00"), serialized
+ # And it round-trips through a strict parser unchanged.
+ assert datetime.fromisoformat(serialized) == ts
+
+
+def test_autogen_record_metrics_timestamp_is_utc() -> None:
+ collector = AutogenCollector()
+ autogen_record(collector, "search", "the original tool output", "short", True)
+ _assert_utc(collector.metrics[0].timestamp)
+
+
+def test_crewai_record_metrics_timestamp_is_utc() -> None:
+ collector = CrewaiCollector()
+ wrapper = SimpleNamespace(name="search", _metrics=collector)
+ # Unbound call with a duck-typed self avoids constructing the CrewAI BaseTool.
+ CrewaiWrapper._record_metrics(wrapper, "the original tool output", "short", True)
+ _assert_utc(collector.metrics[0].timestamp)
+
+
+def test_langchain_record_metrics_timestamp_is_utc() -> None:
+ collector = LangchainCollector()
+ wrapper = SimpleNamespace(name="search", _metrics=collector)
+ LangchainWrapper._record_metrics(wrapper, "the original tool output", "short", True)
+ _assert_utc(collector.metrics[0].timestamp)
+
+
+def test_langsmith_exported_optimization_timestamp_is_utc() -> None:
+ """The actual telemetry serialization seam must emit an aware UTC offset.
+
+ ``HeadroomLangSmithCallbackHandler._attach_metrics_to_run`` is the real
+ persistence/format path: it serializes ``PendingMetrics.timestamp`` via
+ ``.isoformat()`` into the exported ``headroom.optimization_timestamp``
+ LangSmith metadata field. Regression: ``PendingMetrics`` defaulted its
+ timestamp to a naive local ``datetime.now()``, so the exported string
+ carried no offset and a downstream reader silently mis-read it as UTC.
+
+ The handler imports LangChain lazily and the export seam does not touch
+ the framework, so it is exercised unbound with a duck-typed ``self`` —
+ no langchain/langsmith install required.
+ """
+ from headroom.integrations.langchain.langsmith import (
+ HeadroomLangSmithCallbackHandler,
+ PendingMetrics,
+ )
+
+ # The default-constructed timestamp (the recording seam) is UTC-aware.
+ metrics = PendingMetrics(
+ tokens_before=100,
+ tokens_after=40,
+ tokens_saved=60,
+ savings_percent=60.0,
+ transforms_applied=["code"],
+ )
+ _assert_utc(metrics.timestamp)
+
+ # Drive the real export code path (metrics.timestamp.isoformat()).
+ handler = SimpleNamespace(_run_metrics={}, _client=None, _auto_update=False)
+ HeadroomLangSmithCallbackHandler._attach_metrics_to_run(handler, "run-1", metrics)
+
+ serialized = handler._run_metrics["run-1"]["headroom.optimization_timestamp"]
+ assert serialized.endswith("+00:00"), serialized
+ assert datetime.fromisoformat(serialized).utcoffset() == timedelta(0)