feat: improve OpenTelemetry config and warnings

Author: Pouyanpi

examples/configs/tracing/README.md

@@ -18,6 +18,7 @@ Tracing helps you understand what happens inside your guardrails:
 The fastest way to see tracing in action:
 
 ```bash
+# Install tracing support with SDK (needed for examples)
 pip install nemoguardrails[tracing] opentelemetry-sdk
 
 cd examples/configs/tracing/
@@ -109,11 +110,35 @@ This means you must configure OpenTelemetry in your application code.
 
 ### Installation
 
+#### For Tracing Support (API only)
+
+```bash
+# minimum requirement for NeMo Guardrails tracing features
+pip install nemoguardrails[tracing]
+```
+
+This installs only the OpenTelemetry API, which is sufficient if your application already configures OpenTelemetry.
+
+#### For Running Examples and Development
+
+```bash
+# includes OpenTelemetry SDK for configuring exporters
+pip install nemoguardrails[tracing] opentelemetry-sdk
+```
+
+#### For Production Deployments
+
 ```bash
+# install tracing support
 pip install nemoguardrails[tracing]
 
-# install OpenTelemetry SDK and exporters (required for your application)
-pip install opentelemetry-sdk
+# install SDK and your preferred exporter
+# for TLP
+pip install opentelemetry-sdk opentelemetry-exporter-otlp
+# OR for Jaeger
+pip install opentelemetry-sdk opentelemetry-exporter-jaeger
+# OR for Zipkin
+pip install opentelemetry-sdk opentelemetry-exporter-zipkin
 ```
 
 ### Configuration Examples

examples/configs/tracing/working_example.py

@@ -88,6 +88,18 @@ def create_guardrails_config():
                 }
             ],
             "tracing": {"enabled": True, "adapters": [{"name": "OpenTelemetry"}]},
+            # Note: The following old-style configuration is deprecated and will be ignored:
+            # "tracing": {
+            #     "enabled": True,
+            #     "adapters": [{
+            #         "name": "OpenTelemetry",
+            #         "service_name": "my-service",      # DEPRECATED - configure in Resource
+            #         "exporter": "console",             # DEPRECATED - configure SDK
+            #         "resource_attributes": {           # DEPRECATED - configure in Resource
+            #             "env": "production"
+            #         }
+            #     }]
+            # }
         },
     )
 

nemoguardrails/tracing/adapters/opentelemetry.py

@@ -53,13 +53,15 @@
 
 from __future__ import annotations
 
+import warnings
 from importlib.metadata import version
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from nemoguardrails.tracing import InteractionLog
 try:
     from opentelemetry import trace
+    from opentelemetry.trace import NoOpTracerProvider
 
 except ImportError:
     raise ImportError(
@@ -97,6 +99,37 @@ def __init__(
             Applications must configure the OpenTelemetry SDK before using this adapter.
             The adapter will use the globally configured tracer provider.
         """
+        # check for deprecated parameters and warn users
+        deprecated_params = [
+            "exporter",
+            "exporter_cls",
+            "resource_attributes",
+            "span_processor",
+        ]
+        used_deprecated = [param for param in deprecated_params if param in kwargs]
+
+        if used_deprecated:
+            warnings.warn(
+                f"OpenTelemetry configuration parameters {used_deprecated} in YAML/config are deprecated "
+                "and will be ignored. Please configure OpenTelemetry in your application code. "
+                "See the migration guide at: "
+                "https://github.com/NVIDIA/NeMo-Guardrails/blob/main/examples/configs/tracing/README.md#migration-guide",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        # validate that OpenTelemetry is properly configured
+        provider = trace.get_tracer_provider()
+        if provider is None or isinstance(provider, NoOpTracerProvider):
+            warnings.warn(
+                "No OpenTelemetry TracerProvider configured. Traces will not be exported. "
+                "Please configure OpenTelemetry in your application code before using NeMo Guardrails. "
+                "See setup guide at: "
+                "https://github.com/NVIDIA/NeMo-Guardrails/blob/main/examples/configs/tracing/README.md#opentelemetry-setup",
+                UserWarning,
+                stacklevel=2,
+            )
+
         self.tracer = trace.get_tracer(
             service_name,
             instrumenting_library_version=version("nemoguardrails"),

tests/test_tracing_adapters_opentelemetry.py

@@ -15,14 +15,15 @@
 
 import asyncio
 import unittest
+import warnings
 from importlib.metadata import version
 from unittest.mock import MagicMock, patch
 
 # TODO: check to see if we can add it as a dependency
 # but now we try to import opentelemetry and set a flag if it's not available
 try:
-    from opentelemetry import trace
     from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.trace import NoOpTracerProvider
 
     from nemoguardrails.tracing.adapters.opentelemetry import OpenTelemetryAdapter
 
@@ -288,3 +289,55 @@ def test_backward_compatibility_with_old_config(self):
         # Should still create the adapter successfully
         self.assertIsInstance(adapter, OpenTelemetryAdapter)
         self.assertEqual(adapter.tracer, self.mock_tracer)
+
+    def test_deprecation_warning_for_old_parameters(self):
+        """Test that deprecation warnings are raised for old configuration parameters."""
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+
+            # adapter with deprecated parameters
+            _adapter = OpenTelemetryAdapter(
+                service_name="test_service",
+                exporter="console",
+                resource_attributes={"test": "value"},
+                span_processor=MagicMock(),
+            )
+
+            # deprecation warning is issued
+            self.assertEqual(len(w), 1)
+            self.assertTrue(issubclass(w[0].category, DeprecationWarning))
+            self.assertIn("deprecated", str(w[0].message))
+            self.assertIn("exporter", str(w[0].message))
+            self.assertIn("resource_attributes", str(w[0].message))
+            self.assertIn("span_processor", str(w[0].message))
+
+    def test_no_op_tracer_provider_warning(self):
+        """Test that a warning is issued when NoOpTracerProvider is detected."""
+
+        with patch("opentelemetry.trace.get_tracer_provider") as mock_get_provider:
+            mock_get_provider.return_value = NoOpTracerProvider()
+
+            with warnings.catch_warnings(record=True) as w:
+                warnings.simplefilter("always")
+
+                _adapter = OpenTelemetryAdapter()
+
+                self.assertEqual(len(w), 1)
+                self.assertTrue(issubclass(w[0].category, UserWarning))
+                self.assertIn(
+                    "No OpenTelemetry TracerProvider configured", str(w[0].message)
+                )
+                self.assertIn("Traces will not be exported", str(w[0].message))
+
+    def test_no_warnings_with_proper_configuration(self):
+        """Test that no warnings are issued when properly configured."""
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+
+            # adapter without deprecated parameters
+            _adapter = OpenTelemetryAdapter(service_name="test_service")
+
+            # no warnings is issued
+            self.assertEqual(len(w), 0)