clean-up repeated inline import in tracing metrics recording module

Author: james-cardenas

src/agentex/lib/core/observability/tests/test_tracing_metrics_recording.py

@@ -15,6 +15,7 @@ def __init__(self, enqueued_at: float | None) -> None:
 class TestIsMetricsEnabled:
     def setup_method(self) -> None:
         recording._metrics_enabled = None
+        recording._tracing = None
 
     def test_enabled_by_default(self, monkeypatch):
         monkeypatch.delenv("AGENTEX_TRACING_METRICS", raising=False)
@@ -29,6 +30,7 @@ def test_disabled_by_zero(self, monkeypatch):
 class TestRecordingHelpers:
     def setup_method(self) -> None:
         recording._metrics_enabled = None
+        recording._tracing = None
 
     def test_record_span_enqueued_when_disabled_does_not_load_metrics(self, monkeypatch):
         monkeypatch.setenv("AGENTEX_TRACING_METRICS", "0")

src/agentex/lib/core/observability/tracing_metrics_recording.py

@@ -17,6 +17,7 @@ class _HasEnqueuedAt(Protocol):
 
 
 _metrics_enabled: bool | None = None
+_tracing = None  # lazy-loaded tracing_metrics module (loads OTel on first use)
 
 
 def is_metrics_enabled() -> bool:
@@ -28,6 +29,16 @@ def is_metrics_enabled() -> bool:
     return _metrics_enabled
 
 
+def _tracing_module():
+    """Return lazy-loaded ``tracing_metrics`` module (loads OTel on first use)."""
+    global _tracing
+    if _tracing is None:
+        from agentex.lib.core.observability import tracing_metrics
+
+        _tracing = tracing_metrics
+    return _tracing
+
+
 def monotonic_if_enabled() -> float | None:
     """Return ``time.monotonic()`` when metrics are enabled, else ``None``."""
     if not is_metrics_enabled():
@@ -39,9 +50,9 @@ def record_span_enqueued(event_type: str) -> None:
     if not is_metrics_enabled():
         return
     try:
-        from agentex.lib.core.observability.tracing_metrics import get_tracing_metrics
-
-        get_tracing_metrics().span_events_enqueued.add(1, {"event_type": event_type})
+        _tracing_module().get_tracing_metrics().span_events_enqueued.add(
+            1, {"event_type": event_type}
+        )
     except Exception:
         pass
 
@@ -50,9 +61,7 @@ def record_span_dropped(reason: str) -> None:
     if not is_metrics_enabled():
         return
     try:
-        from agentex.lib.core.observability.tracing_metrics import get_tracing_metrics
-
-        get_tracing_metrics().span_events_dropped.add(1, {"reason": reason})
+        _tracing_module().get_tracing_metrics().span_events_dropped.add(1, {"reason": reason})
     except Exception:
         pass
 
@@ -65,9 +74,7 @@ def record_batch_coalesced(
     if not is_metrics_enabled():
         return
     try:
-        from agentex.lib.core.observability.tracing_metrics import get_tracing_metrics
-
-        metrics = get_tracing_metrics()
+        metrics = _tracing_module().get_tracing_metrics()
         metrics.queue_depth.record(max(queue_depth, 0))
         metrics.batch_items.record(len(batch_items))
 
@@ -87,10 +94,8 @@ def record_batch_phase(*, phase: str, size: int, duration_ms: float) -> None:
     if not is_metrics_enabled():
         return
     try:
-        from agentex.lib.core.observability.tracing_metrics import get_tracing_metrics
-
         attrs = {"phase": phase}
-        metrics = get_tracing_metrics()
+        metrics = _tracing_module().get_tracing_metrics()
         metrics.batch_size.record(size, attrs)
         metrics.batch_drain_duration.record(duration_ms, attrs)
     except Exception:
@@ -101,10 +106,8 @@ def record_export_success(*, event_type: str, span_count: int, processor: str =
     if not is_metrics_enabled():
         return
     try:
-        from agentex.lib.core.observability.tracing_metrics import get_tracing_metrics
-
         attrs = {"processor": processor, "event_type": event_type}
-        metrics = get_tracing_metrics()
+        metrics = _tracing_module().get_tracing_metrics()
         metrics.export_batches.add(1, attrs)
         metrics.export_spans.add(span_count, attrs)
     except Exception:
@@ -121,21 +124,16 @@ def record_export_failure(
     if not is_metrics_enabled():
         return
     try:
-        from agentex.lib.core.observability.tracing_metrics import (
-            processor_label,
-            get_tracing_metrics,
-            classify_export_error,
-        )
-
-        error_class, http_code = classify_export_error(exc)
-        proc = processor_label(processor)
+        tm = _tracing_module()
+        error_class, http_code = tm.classify_export_error(exc)
+        proc = tm.processor_label(processor)
         attrs = {
             "processor": proc,
             "event_type": event_type,
             "http_code": http_code,
             "error_class": error_class,
         }
-        metrics = get_tracing_metrics()
+        metrics = tm.get_tracing_metrics()
         metrics.export_batch_failures.add(1, attrs)
         metrics.export_span_failures.add(span_count, attrs)
     except Exception:
@@ -146,9 +144,7 @@ def record_shutdown_timeout(*, remaining_items: int) -> None:
     if not is_metrics_enabled():
         return
     try:
-        from agentex.lib.core.observability.tracing_metrics import get_tracing_metrics
-
-        metrics = get_tracing_metrics()
+        metrics = _tracing_module().get_tracing_metrics()
         metrics.shutdown_timeouts.add(1)
         metrics.shutdown_remaining_items.record(max(remaining_items, 0))
     except Exception:

tests/lib/core/tracing/processors/test_sgp_tracing_processor.py

@@ -227,6 +227,7 @@ async def test_on_spans_start_records_export_success_metrics(self, monkeypatch):
         import agentex.lib.core.observability.tracing_metrics_recording as recording
 
         recording._metrics_enabled = None
+        recording._tracing = None
         processor, _, mock_client = self._make_processor()
         mock_metrics = MagicMock()
 

tests/lib/core/tracing/test_span_queue.py

@@ -531,6 +531,7 @@ async def test_enqueue_records_enqueued_metric(self, monkeypatch):
         import agentex.lib.core.observability.tracing_metrics_recording as recording
 
         recording._metrics_enabled = None
+        recording._tracing = None
         mock_metrics = MagicMock()
         proc = _make_processor()
         queue = AsyncSpanQueue()
@@ -550,6 +551,7 @@ async def test_processor_failure_records_export_failure(self, monkeypatch):
         import agentex.lib.core.observability.tracing_metrics_recording as recording
 
         recording._metrics_enabled = None
+        recording._tracing = None
         mock_metrics = MagicMock()
 
         class ExportError(Exception):
@@ -576,6 +578,7 @@ async def test_enqueue_overhead_with_metrics_disabled(self, monkeypatch):
         import agentex.lib.core.observability.tracing_metrics_recording as recording
 
         recording._metrics_enabled = None
+        recording._tracing = None
         proc = _make_processor()
         queue = AsyncSpanQueue()