feat: enhance tracing system with OpenTelemetry semantic conventions (#1331)

* feat: enhance tracing system with OpenTelemetry semantic conventions and configurable span formats

Introduces a major enhancement to the NeMo Guardrails tracing and telemetry infrastructure with support for multiple span formats, OpenTelemetry semantic convention compliance, and privacy-focused content capture controls. The system now supports both legacy and OpenTelemetry-compliant span formats while maintaining backward compatibility.

Key changes:
- Add configurable span format support (flat/opentelemetry)
- Implement OpenTelemetry semantic conventions for GenAI
- Add privacy controls for prompt/response content capture
- Enhance LLM call tracking with model provider information
- Improve span extraction and modeling architecture
- Add comprehensive test coverage for new functionality

Author: Pouyanpi

nemoguardrails/actions/llm/utils.py

@@ -66,6 +66,8 @@ def _infer_model_name(llm: BaseLanguageModel):
 async def llm_call(
     llm: BaseLanguageModel,
     prompt: Union[str, List[dict]],
+    model_name: Optional[str] = None,
+    model_provider: Optional[str] = None,
     stop: Optional[List[str]] = None,
     custom_callback_handlers: Optional[List[AsyncCallbackHandler]] = None,
 ) -> str:
@@ -76,7 +78,8 @@ async def llm_call(
         llm_call_info = LLMCallInfo()
         llm_call_info_var.set(llm_call_info)
 
-    llm_call_info.llm_model_name = _infer_model_name(llm)
+    llm_call_info.llm_model_name = model_name or _infer_model_name(llm)
+    llm_call_info.llm_provider_name = model_provider
 
     if custom_callback_handlers and custom_callback_handlers != [None]:
         all_callbacks = BaseCallbackManager(

nemoguardrails/logging/explain.py

@@ -59,6 +59,10 @@ class LLMCallInfo(LLMCallSummary):
         default="unknown",
         description="The name of the model use for the LLM call.",
     )
+    llm_provider_name: Optional[str] = Field(
+        default="unknown",
+        description="The provider of the model used for the LLM call, e.g. 'openai', 'nvidia'.",
+    )
 
 
 class ExplainInfo(BaseModel):

nemoguardrails/rails/llm/config.py

@@ -358,12 +358,29 @@ class LogAdapterConfig(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
+class SpanFormat(str, Enum):
+    legacy = "legacy"
+    opentelemetry = "opentelemetry"
+
+
 class TracingConfig(BaseModel):
     enabled: bool = False
     adapters: List[LogAdapterConfig] = Field(
         default_factory=lambda: [LogAdapterConfig()],
         description="The list of tracing adapters to use. If not specified, the default adapters are used.",
     )
+    span_format: str = Field(
+        default=SpanFormat.opentelemetry,
+        description="The span format to use. Options are 'legacy' (simple metrics) or 'opentelemetry' (OpenTelemetry semantic conventions).",
+    )
+    enable_content_capture: bool = Field(
+        default=False,
+        description=(
+            "Capture prompts and responses (user/assistant/tool message content) in tracing/telemetry events. "
+            "Disabled by default for privacy and alignment with OpenTelemetry GenAI semantic conventions. "
+            "WARNING: Enabling this may include PII and sensitive data in your telemetry backend."
+        ),
+    )
 
 
 class EmbeddingsCacheConfig(BaseModel):

nemoguardrails/rails/llm/llmrails.py

@@ -244,6 +244,8 @@ def __init__(
             from nemoguardrails.tracing import create_log_adapters
 
             self._log_adapters = create_log_adapters(config.tracing)
+        else:
+            self._log_adapters = None
 
         # We run some additional checks on the config
         self._validate_config()
@@ -1167,9 +1169,19 @@ async def generate_async(
                 # lazy import to avoid circular dependency
                 from nemoguardrails.tracing import Tracer
 
-                # Create a Tracer instance with instantiated adapters
+                span_format = getattr(
+                    self.config.tracing, "span_format", "opentelemetry"
+                )
+                enable_content_capture = getattr(
+                    self.config.tracing, "enable_content_capture", False
+                )
+                # Create a Tracer instance with instantiated adapters and span configuration
                 tracer = Tracer(
-                    input=messages, response=res, adapters=self._log_adapters
+                    input=messages,
+                    response=res,
+                    adapters=self._log_adapters,
+                    span_format=span_format,
+                    enable_content_capture=enable_content_capture,
                 )
                 await tracer.export_async()
 

nemoguardrails/tracing/__init__.py

@@ -13,4 +13,24 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from .tracer import InteractionLog, Tracer, create_log_adapters
+from .interaction_types import InteractionLog, InteractionOutput
+from .span_extractors import (
+    SpanExtractor,
+    SpanExtractorV1,
+    SpanExtractorV2,
+    create_span_extractor,
+)
+from .spans import SpanEvent, SpanLegacy, SpanOpentelemetry
+from .tracer import Tracer, create_log_adapters
+
+___all__ = [
+    SpanExtractor,
+    SpanExtractorV1,
+    SpanExtractorV2,
+    create_span_extractor,
+    Tracer,
+    create_log_adapters,
+    SpanEvent,
+    SpanLegacy,
+    SpanOpentelemetry,
+]

nemoguardrails/tracing/adapters/base.py

@@ -16,7 +16,7 @@
 from abc import ABC, abstractmethod
 from typing import Optional
 
-from nemoguardrails.eval.models import InteractionLog
+from nemoguardrails.tracing.interaction_types import InteractionLog
 
 
 class InteractionLogAdapter(ABC):

nemoguardrails/tracing/adapters/filesystem.py

@@ -24,6 +24,10 @@
     from nemoguardrails.tracing import InteractionLog
 
 from nemoguardrails.tracing.adapters.base import InteractionLogAdapter
+from nemoguardrails.tracing.span_formatting import (
+    format_span_for_filesystem,
+    get_schema_version_for_filesystem,
+)
 
 
 class FileSystemAdapter(InteractionLogAdapter):
@@ -38,56 +42,46 @@ def __init__(self, filepath: Optional[str] = None):
 
     def transform(self, interaction_log: "InteractionLog"):
         """Transforms the InteractionLog into a JSON string."""
-        spans = []
-
-        for span_data in interaction_log.trace:
-            span_dict = {
-                "name": span_data.name,
-                "span_id": span_data.span_id,
-                "parent_id": span_data.parent_id,
-                "trace_id": interaction_log.id,
-                "start_time": span_data.start_time,
-                "end_time": span_data.end_time,
-                "duration": span_data.duration,
-                "metrics": span_data.metrics,
-            }
-            spans.append(span_dict)
+        spans = [
+            format_span_for_filesystem(span_data) for span_data in interaction_log.trace
+        ]
+
+        if not interaction_log.trace:
+            schema_version = None
+        else:
+            schema_version = get_schema_version_for_filesystem(interaction_log.trace[0])
 
         log_dict = {
+            "schema_version": schema_version,
             "trace_id": interaction_log.id,
             "spans": spans,
         }
 
-        with open(self.filepath, "a") as f:
-            f.write(json.dumps(log_dict, indent=2) + "\n")
+        with open(self.filepath, "a", encoding="utf-8") as f:
+            f.write(json.dumps(log_dict) + "\n")
 
     async def transform_async(self, interaction_log: "InteractionLog"):
         try:
             import aiofiles
         except ImportError:
             raise ImportError(
-                "aiofiles is required for async file writing. Please install it using `pip install aiofiles"
+                "aiofiles is required for async file writing. Please install it using `pip install aiofiles`"
             )
 
-        spans = []
-
-        for span_data in interaction_log.trace:
-            span_dict = {
-                "name": span_data.name,
-                "span_id": span_data.span_id,
-                "parent_id": span_data.parent_id,
-                "trace_id": interaction_log.id,
-                "start_time": span_data.start_time,
-                "end_time": span_data.end_time,
-                "duration": span_data.duration,
-                "metrics": span_data.metrics,
-            }
-            spans.append(span_dict)
+        spans = [
+            format_span_for_filesystem(span_data) for span_data in interaction_log.trace
+        ]
+
+        if not interaction_log.trace:
+            schema_version = None
+        else:
+            schema_version = get_schema_version_for_filesystem(interaction_log.trace[0])
 
         log_dict = {
+            "schema_version": schema_version,
             "trace_id": interaction_log.id,
             "spans": spans,
         }
 
-        async with aiofiles.open(self.filepath, "a") as f:
-            await f.write(json.dumps(log_dict, indent=2) + "\n")
+        async with aiofiles.open(self.filepath, "a", encoding="utf-8") as f:
+            await f.write(json.dumps(log_dict) + "\n")