fix: move otel check to client init time to avoid timing issue (#1958)

**Issue:** for dynamic values like env var, you usually want to check
them inside the instance or function, not at import time. because under
the hood, python Imports are cached (in sys.modules), so in the case of
some customer who's using pytest with otel, their second import of
langsmith.client (during pytest unit test run time) weren't able to
override initial one (during langsmith_plugin pytest plugin import,
happened at very first of pytest set up). This is causing subtle issue
like if pytest plugin run first (`has_otel=False`), then later even if
env var got reset (`has_otel=True`) the python still doesn't recognize
the change.

I also found that the env var cache a bit problematic in such case, but
if we fix the import, that might be less concerning, so i just reduced
max size a little bit to make it less likely to be an issue.

Author: EugeneJinXin

python/langsmith/__init__.py

@@ -21,7 +21,7 @@
 
 # Avoid calling into importlib on every call to __version__
 
-__version__ = "0.4.16"
+__version__ = "0.4.17"
 version = __version__  # for backwards compatibility
 
 

python/langsmith/_internal/otel/_otel_client.py

@@ -1,12 +1,21 @@
 """Client configuration for OpenTelemetry integration with LangSmith."""
 
 import os
+import warnings
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    try:
+        from opentelemetry.sdk.trace import TracerProvider  # type: ignore[import]
+    except ImportError:
+        TracerProvider = object  # type: ignore[assignment, misc]
 
 from langsmith import utils as ls_utils
 
-HAS_OTEL = False
-try:
-    if ls_utils.is_truish(ls_utils.get_env_var("OTEL_ENABLED")):
+
+def _import_otel_client():
+    """Dynamically import OTEL client modules when needed."""
+    try:
         from opentelemetry.exporter.otlp.proto.http.trace_exporter import (  # type: ignore[import]
             OTLPSpanExporter,
         )
@@ -19,9 +28,18 @@
             BatchSpanProcessor,
         )
 
-        HAS_OTEL = True
-except ImportError:
-    pass
+        return (
+            OTLPSpanExporter,
+            SERVICE_NAME,
+            Resource,
+            TracerProvider,
+            BatchSpanProcessor,
+        )
+    except ImportError as e:
+        warnings.warn(
+            f"OTEL_ENABLED is set but OpenTelemetry packages are not installed: {e}"
+        )
+        return None
 
 
 def get_otlp_tracer_provider() -> "TracerProvider":
@@ -40,12 +58,20 @@ def get_otlp_tracer_provider() -> "TracerProvider":
     Returns:
         TracerProvider: The OTLP tracer provider.
     """
-    # Set LangSmith-specific defaults if not already set in environment
-    if not HAS_OTEL:
+    # Import OTEL modules dynamically
+    otel_imports = _import_otel_client()
+    if otel_imports is None:
         raise ImportError(
             "OpenTelemetry packages are required to use this function. "
             "Please install with `pip install langsmith[otel]`"
         )
+    (
+        OTLPSpanExporter,
+        SERVICE_NAME,
+        Resource,
+        TracerProvider,
+        BatchSpanProcessor,
+    ) = otel_imports
 
     if "OTEL_EXPORTER_OTLP_ENDPOINT" not in os.environ:
         ls_endpoint = ls_utils.get_api_url(None)

python/langsmith/_internal/otel/_otel_exporter.py

@@ -6,9 +6,16 @@
 import logging
 import uuid
 import warnings
-from typing import Any, Optional
+from typing import TYPE_CHECKING, Any, Optional
+
+if TYPE_CHECKING:
+    try:
+        from opentelemetry.context.context import Context  # type: ignore[import]
+        from opentelemetry.trace import Span  # type: ignore[import]
+    except ImportError:
+        Context = Any  # type: ignore[assignment, misc]
+        Span = Any  # type: ignore[assignment, misc]
 
-from langsmith import utils as ls_utils
 from langsmith._internal import _orjson
 from langsmith._internal._operations import (
     SerializedRunOperation,
@@ -18,9 +25,10 @@
     get_otel_trace_id_from_uuid,
 )
 
-HAS_OTEL = False
-try:
-    if ls_utils.is_truish(ls_utils.get_env_var("OTEL_ENABLED")):
+
+def _import_otel_exporter():
+    """Dynamically import OTEL exporter modules when needed."""
+    try:
         from opentelemetry import trace  # type: ignore[import]
         from opentelemetry.context.context import Context  # type: ignore[import]
         from opentelemetry.trace import (  # type: ignore[import]
@@ -32,9 +40,22 @@
             set_span_in_context,
         )
 
-        HAS_OTEL = True
-except ImportError:
-    pass
+        return (
+            trace,
+            Context,
+            NonRecordingSpan,
+            Span,
+            SpanContext,
+            TraceFlags,
+            TraceState,
+            set_span_in_context,
+        )
+    except ImportError as e:
+        warnings.warn(
+            f"OTEL_ENABLED is set but OpenTelemetry packages are not installed: {e}"
+        )
+        return None
+
 
 logger = logging.getLogger(__name__)
 
@@ -97,7 +118,7 @@ def _get_operation_name(run_type: str) -> str:
 
 
 class OTELExporter:
-    __slots__ = ["_tracer", "_spans"]
+    __slots__ = ["_tracer", "_spans", "_otel_available", "_trace"]
     """OpenTelemetry exporter for LangSmith runs."""
 
     def __init__(self, tracer_provider=None):
@@ -107,15 +128,30 @@ def __init__(self, tracer_provider=None):
             tracer_provider: Optional tracer provider to use. If not provided,
                 the global tracer provider will be used.
         """
-        if not HAS_OTEL:
-            warnings.warn(
-                "OTEL_ENABLED is set but OpenTelemetry packages are not installed. "
-                "Install with `pip install langsmith[otel]`"
+        otel_imports = _import_otel_exporter()
+        if otel_imports is None:
+            self._tracer = None
+            self._spans = {}
+            self._otel_available = False
+            self._trace = None
+        else:
+            (
+                trace,
+                Context,
+                NonRecordingSpan,
+                Span,
+                SpanContext,
+                TraceFlags,
+                TraceState,
+                set_span_in_context,
+            ) = otel_imports
+
+            self._tracer = trace.get_tracer(
+                "langsmith", tracer_provider=tracer_provider
             )
-            return
-
-        self._tracer = trace.get_tracer("langsmith", tracer_provider=tracer_provider)
-        self._spans = {}
+            self._spans = {}
+            self._otel_available = True
+            self._trace = trace
 
     def export_batch(
         self,
@@ -191,6 +227,21 @@ def _create_span_for_run(
             trace_id_int = get_otel_trace_id_from_uuid(op.trace_id)
             span_id_int = get_otel_span_id_from_uuid(op.id)
 
+            # Get OTEL imports for this operation
+            otel_imports = _import_otel_exporter()
+            if otel_imports is None:
+                return None
+            (
+                trace,
+                Context,
+                NonRecordingSpan,
+                Span,
+                SpanContext,
+                TraceFlags,
+                TraceState,
+                set_span_in_context,
+            ) = otel_imports
+
             # Create SpanContext with deterministic IDs
             span_context = SpanContext(
                 trace_id=trace_id_int,
@@ -268,10 +319,10 @@ def _update_span_for_run(self, op: SerializedRunOperation, run_info: dict) -> No
             self._set_span_attributes(span, run_info, op)
             # Update status based on error
             if run_info.get("error"):
-                span.set_status(trace.StatusCode.ERROR)
+                span.set_status(self._trace.StatusCode.ERROR)
                 span.record_exception(Exception(run_info.get("error")))
             else:
-                span.set_status(trace.StatusCode.OK)
+                span.set_status(self._trace.StatusCode.OK)
 
             # End the span if end_time is present
             end_time = run_info.get("end_time")
@@ -316,7 +367,10 @@ def _extract_model_name(self, run_info: dict) -> Optional[str]:
         return None
 
     def _set_span_attributes(
-        self, span: Span, run_info: dict, op: SerializedRunOperation
+        self,
+        span: Span,
+        run_info: dict,
+        op: SerializedRunOperation,
     ) -> None:
         """Set attributes on the span.