Clarify telemetry helper opt-in API

Author: rbarbadillo

src/mistralai/extra/observability/telemetry.py

@@ -81,14 +81,15 @@ def _has_otel_exporter_endpoint_env() -> bool:
     )
 
 
-def configure_telemetry(
-    client: "Mistral",
-    telemetry: bool | None = None,
-) -> bool:
+def configure_telemetry(client: "Mistral") -> bool:
     """Configure an isolated telemetry provider for a Mistral client.
 
+    Calling configure_telemetry(client) explicitly enables SDK telemetry.
+    Environment and SDKConfiguration-based auto-resolution are handled by the
+    request hook.
+
     Returns True when telemetry is enabled and a provider is attached. Returns
-    False when telemetry is disabled or a non-telemetry provider is already set.
+    False when a non-telemetry provider is already set.
     """
     hooks = getattr(client.sdk_configuration, "_hooks", None)
     if hooks is None:
@@ -97,7 +98,7 @@ def configure_telemetry(
     return configure_telemetry_for_hook(
         _get_tracing_hook(hooks),
         client.sdk_configuration,
-        telemetry=telemetry,
+        telemetry=True,
         finalizer_owner=client,
     )
 
@@ -111,11 +112,10 @@ def configure_telemetry_for_hook(
 ) -> bool:
     """Configure telemetry for a tracing hook when the user has opted in."""
     # Fast path: already resolved and no explicit override requested.
-    if telemetry is None:
-        if hook._auto_telemetry_provider is not None:
-            return True
-        if hook._telemetry_auto_disabled:
-            return False
+    if hook._auto_telemetry_provider is not None and telemetry is not False:
+        return True
+    if telemetry is None and hook._telemetry_auto_disabled:
+        return False
 
     telemetry_setting = telemetry
     if telemetry_setting is None:

src/mistralai/extra/tests/test_telemetry.py

@@ -141,7 +141,7 @@ def test_configure_telemetry_attaches_per_client_provider(self):
                 return_value=provider,
             ) as create_provider:
                 client = _make_client(api_key="test-key")
-                configured = configure_telemetry(client, telemetry=True)
+                configured = configure_telemetry(client)
 
         self.assertTrue(configured)
         create_provider.assert_called_once_with(
@@ -150,19 +150,24 @@ def test_configure_telemetry_attaches_per_client_provider(self):
         )
         self.assertIs(_get_tracing_hook(client).tracer_provider, provider)
 
-    def test_explicit_false_overrides_env_true(self):
+    def test_internal_explicit_false_overrides_env_true(self):
         with patch.dict(os.environ, {MISTRAL_SDK_TELEMETRY_ENV: "true"}, clear=True):
             with patch(
                 "mistralai.extra.observability.telemetry._create_telemetry_tracer_provider"
             ) as create_provider:
                 client = _make_client(api_key="test-key")
-                configured = configure_telemetry(client, telemetry=False)
+                hook = _get_tracing_hook(client)
+                configured = configure_telemetry_for_hook(
+                    hook,
+                    client.sdk_configuration,
+                    telemetry=False,
+                )
 
         self.assertFalse(configured)
         create_provider.assert_not_called()
         self.assertIsNone(_get_tracing_hook(client).tracer_provider)
 
-    def test_explicit_false_disables_auto_telemetry_provider(self):
+    def test_internal_explicit_false_disables_auto_telemetry_provider(self):
         provider = FakeProvider()
 
         with patch.dict(os.environ, {}, clear=True):
@@ -171,8 +176,13 @@ def test_explicit_false_disables_auto_telemetry_provider(self):
                 return_value=provider,
             ):
                 client = _make_client(api_key="test-key")
-                configure_telemetry(client, telemetry=True)
-                configured = configure_telemetry(client, telemetry=False)
+                configure_telemetry(client)
+                hook = _get_tracing_hook(client)
+                configured = configure_telemetry_for_hook(
+                    hook,
+                    client.sdk_configuration,
+                    telemetry=False,
+                )
 
         self.assertFalse(configured)
         self.assertTrue(provider.shutdown_called)
@@ -191,7 +201,11 @@ def test_env_true_uses_mistral_api_key_fallback(self):
                 return_value=provider,
             ) as create_provider:
                 client = _make_client(api_key=None)
-                configured = configure_telemetry(client)
+                hook = _get_tracing_hook(client)
+                configured = configure_telemetry_for_hook(
+                    hook,
+                    client.sdk_configuration,
+                )
 
         self.assertTrue(configured)
         create_provider.assert_called_once_with(
@@ -215,7 +229,7 @@ def test_otel_endpoint_env_configures_without_mistral_api_key(self):
                     return_value=provider,
                 ) as create_provider:
                     client = _make_client(api_key=None)
-                    configured = configure_telemetry(client, telemetry=True)
+                    configured = configure_telemetry(client)
 
         self.assertTrue(configured)
         resolve_api_key.assert_not_called()
@@ -241,7 +255,11 @@ def test_env_true_prefers_otel_endpoint_env_over_mistral_endpoint(self):
                     return_value=provider,
                 ) as create_provider:
                     client = _make_client(api_key=None)
-                    configured = configure_telemetry(client)
+                    hook = _get_tracing_hook(client)
+                    configured = configure_telemetry_for_hook(
+                        hook,
+                        client.sdk_configuration,
+                    )
 
         self.assertTrue(configured)
         resolve_api_key.assert_not_called()
@@ -263,7 +281,7 @@ def test_missing_optional_dependencies_raise_install_hint(self):
                     TelemetryConfigurationError,
                     r"mistralai\[telemetry\]",
                 ):
-                    configure_telemetry(client, telemetry=True)
+                    configure_telemetry(client)
 
     def test_manual_provider_replaces_auto_telemetry_provider(self):
         provider = FakeProvider()
@@ -275,7 +293,7 @@ def test_manual_provider_replaces_auto_telemetry_provider(self):
                 return_value=provider,
             ):
                 client = _make_client(api_key="test-key")
-                configure_telemetry(client, telemetry=True)
+                configure_telemetry(client)
 
         set_tracer_provider(client, manual_provider)