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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
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.pyindex a83abbd1a..ca78375fc 100644--- a/headroom/integrations/autogen/agents.py+++ b/headroom/integrations/autogen/agents.py@@ -36,7 +36,7 @@ import asyncioimport functoolsimport loggingfrom dataclasses import dataclass, field-from datetime import datetime+from datetime import datetime, timezonefrom typing import Anytry:@@ -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.pyindex e96de992a..6cb54870a 100644--- a/headroom/integrations/crewai/agents.py+++ b/headroom/integrations/crewai/agents.py@@ -26,7 +26,7 @@ from __future__ import annotationsimport loggingfrom dataclasses import dataclass, field-from datetime import datetime+from datetime import datetime, timezonefrom typing import Anytry:@@ -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.pyindex 26b1c0e35..1fb4dab52 100644--- a/headroom/integrations/langchain/agents.py+++ b/headroom/integrations/langchain/agents.py@@ -25,7 +25,7 @@ from __future__ import annotationsimport loggingfrom dataclasses import dataclass, field-from datetime import datetime+from datetime import datetime, timezonefrom 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.pyindex b9b51452c..871f6b44f 100644--- a/headroom/integrations/langchain/chat_model.py+++ b/headroom/integrations/langchain/chat_model.py@@ -33,7 +33,7 @@ import jsonimport loggingfrom collections.abc import AsyncIterator, Iterator, Sequencefrom dataclasses import dataclass-from datetime import datetime+from datetime import datetime, timezonefrom typing import Anyfrom uuid import UUID, uuid4@@ -350,7 +350,7 @@ class HeadroomChatModel(BaseChatModel):# Create metricsmetrics = 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 metricsmetrics = 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.pyindex 6dfb4930f..f7bd14359 100644--- a/headroom/integrations/langchain/langsmith.py+++ b/headroom/integrations/langchain/langsmith.py@@ -39,7 +39,7 @@ from __future__ import annotationsimport loggingimport osfrom dataclasses import dataclass, field-from datetime import datetime+from datetime import datetime, timezonefrom typing import Anyfrom uuid import UUID@@ -86,7 +86,7 @@ class PendingMetrics:tokens_saved: intsavings_percent: floattransforms_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.pynew file mode 100644index 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)