Add opt-in telemetry auto-configuration (#553)

* Add opt-in telemetry auto-configuration

* Clarify telemetry helper opt-in API

* Consolidate telemetry provider configuration

* Isolate dedicated telemetry endpoint config

Author: rbarbadillo

pyproject.toml

@@ -29,6 +29,10 @@ agents = [
 realtime = [
     "websockets >=13.0",
 ]
+telemetry = [
+    "opentelemetry-sdk (>=1.33.1,<2.0.0)",
+    "opentelemetry-exporter-otlp-proto-http (>=1.33.1,<2.0.0)",
+]
 
 workflow_payload_offloading_azure = [
     "azure-storage-blob[aio]>=12.28.0,<13.0.0",
@@ -65,6 +69,7 @@ dev = [
     "mypy==1.15.0",
     "msgpack>=1.1.0,<2.0.0",
     "opentelemetry-sdk (>=1.33.1,<2.0.0)",
+    "opentelemetry-exporter-otlp-proto-http (>=1.33.1,<2.0.0)",
     "pylint==3.2.3",
     "pytest>=8.2.2,<9",
     "pytest-asyncio>=0.23.7,<0.24",

src/mistralai/client/_hooks/tracing.py

@@ -1,5 +1,6 @@
 import logging
-from typing import Optional, Tuple, Union
+import weakref
+from typing import Any, Optional, Tuple, Union
 
 import httpx
 from opentelemetry import trace
@@ -11,6 +12,7 @@
     get_traced_request_and_span,
     get_traced_response,
 )
+from mistralai.extra.observability.telemetry import configure_telemetry_for_hook
 from .types import (
     AfterErrorContext,
     AfterErrorHook,
@@ -29,11 +31,19 @@
 class TracingHook(BeforeRequestHook, AfterSuccessHook, AfterErrorHook):
     def __init__(self) -> None:
         self.tracer_provider: Optional[trace.TracerProvider] = None
+        self._auto_telemetry_provider: Optional[Any] = None
+        self._telemetry_finalizer: Optional[weakref.finalize] = None
+        self._telemetry_auto_disabled: bool = False
         self.tracing_enabled, self.tracer = get_or_create_otel_tracer()
 
     def before_request(
         self, hook_ctx: BeforeRequestContext, request: httpx.Request
     ) -> Union[httpx.Request, Exception]:
+        configure_telemetry_for_hook(
+            self,
+            hook_ctx.config,
+            respect_global_provider=True,
+        )
         # Refresh tracer/provider per request so tracing can be enabled if the
         # application configures OpenTelemetry after the client is instantiated.
         self.tracing_enabled, self.tracer = get_or_create_otel_tracer(

src/mistralai/extra/observability/__init__.py

@@ -4,6 +4,10 @@
 from opentelemetry import trace as otel_trace
 
 from .otel import MISTRAL_SDK_OTEL_TRACER_NAME
+from .telemetry import (
+    TelemetryConfigurationError,
+    configure_telemetry,
+)
 
 if TYPE_CHECKING:
     from mistralai.client.sdk import Mistral
@@ -25,6 +29,9 @@ def set_tracer_provider(
     When set, all SDK spans produced by *client* will be emitted through
     *provider* instead of the global TracerProvider.
 
+    This helper is kept for compatibility. New code can call
+    configure_telemetry(client, provider=provider) directly.
+
     Usage::
 
         from opentelemetry.sdk.trace import TracerProvider
@@ -34,22 +41,12 @@ def set_tracer_provider(
         client = Mistral(api_key="...")
         set_tracer_provider(client, TracerProvider())
     """
-    from mistralai.client._hooks.tracing import TracingHook
-
-    hooks = getattr(client.sdk_configuration, "_hooks", None)
-    if hooks is None:
-        raise ValueError(
-            "Cannot set tracer_provider: SDK hooks not initialised on this client."
-        )
-
-    for hook in hooks.before_request_hooks:
-        if isinstance(hook, TracingHook):
-            hook.tracer_provider = provider
-            return
-
-    raise ValueError(
-        "Cannot set tracer_provider: TracingHook not found in the client's hooks."
-    )
+    configure_telemetry(client, provider=provider)
 
 
-__all__ = ["trace", "set_tracer_provider"]
+__all__ = [
+    "TelemetryConfigurationError",
+    "configure_telemetry",
+    "set_tracer_provider",
+    "trace",
+]