[openai-agents] Map GuardrailSpanData to the semconv run_guardrail span

Adds GuardrailInvocation to opentelemetry-util-genai and stops dropping
agents.tracing.span_data.GuardrailSpanData in GenAITracingProcessor.

gen_ai.guardrail.verdict.type is computed when the span ends because the Agents SDK sets GuardrailSpanData.triggered after the span starts. gen_ai.guardrail.target.type is not emitted from the openai-agents processor because the SDK span data does not record direction.

Assisted-by: GPT-5
Signed-off-by: FugoP <264910004+AgentGymLeader@users.noreply.github.com>

Author: AgentGymLeader

instrumentation/opentelemetry-instrumentation-genai-openai-agents/.changelog/+run-guardrail-span.added

@@ -0,0 +1 @@
+Record OpenAI Agents SDK guardrail tracing data as ``run_guardrail`` spans.

instrumentation/opentelemetry-instrumentation-genai-openai-agents/src/opentelemetry/instrumentation/genai/openai_agents/processor.py

@@ -41,6 +41,7 @@
 from agents.tracing.span_data import (
     AgentSpanData,
     FunctionSpanData,
+    GuardrailSpanData,
 )
 
 from opentelemetry.semconv._incubating.attributes import (
@@ -52,6 +53,7 @@
 from opentelemetry.util.genai.handler import TelemetryHandler
 from opentelemetry.util.genai.invocation import (
     GenAIInvocation,
+    GuardrailInvocation,
     ToolInvocation,
 )
 from opentelemetry.util.genai.types import Error
@@ -126,8 +128,17 @@ def on_span_start(self, span: Span[Any]) -> None:
             )
             self._invocations[span] = invocation
             return
+        if isinstance(span_data, GuardrailSpanData):
+            # GuardrailSpanData does not record whether an input or output guardrail ran.
+            invocation = self._handler.guardrail(
+                span_data.name,
+                provider=self._provider,
+                target_type=None,
+            )
+            self._invocations[span] = invocation
+            return
         # Other span_data types (GenerationSpanData, ResponseSpanData,
-        # HandoffSpanData, GuardrailSpanData, Speech/TranscriptionSpanData)
+        # HandoffSpanData, Speech/TranscriptionSpanData)
         # are intentionally ignored. LLM-level spans come from the openai
         # instrumentation; the rest have no semconv yet.
 
@@ -148,6 +159,10 @@ def on_span_end(self, span: Span[Any]) -> None:
                 invocation.tool_result = (
                     output if isinstance(output, str) else str(output)
                 )
+        if isinstance(invocation, GuardrailInvocation) and isinstance(
+            span.span_data, GuardrailSpanData
+        ):
+            invocation.triggered = span.span_data.triggered
         # SpanError is a mapping, not a raised exception, so it never
         # reaches util-genai's exception path on its own.
         span_error = getattr(span, "error", None)

instrumentation/opentelemetry-instrumentation-genai-openai-agents/tests/test_processor.py

@@ -12,6 +12,7 @@
     AgentSpanData,
     FunctionSpanData,
     GenerationSpanData,
+    GuardrailSpanData,
     HandoffSpanData,
     ResponseSpanData,
 )
@@ -20,6 +21,7 @@
     GenAITracingProcessor,
 )
 from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
 from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
     InMemorySpanExporter,
 )
@@ -84,6 +86,36 @@ def test_agent_span_creates_invoke_local_agent() -> None:
     handler.invoke_local_agent.return_value.stop.assert_called_once_with()
 
 
+@pytest.mark.parametrize(
+    ("triggered", "verdict"),
+    [(False, "allow"), (True, "deny")],
+)
+def test_guardrail_span_creates_guardrail_invocation(
+    triggered: bool, verdict: str
+) -> None:
+    span_exporter = InMemorySpanExporter()
+    tracer_provider = TracerProvider()
+    tracer_provider.add_span_processor(
+        SimpleSpanProcessor(span_exporter)
+    )
+    handler = TelemetryHandler(tracer_provider=tracer_provider)
+    processor = GenAITracingProcessor(handler, provider="openai")
+    span = _Span(GuardrailSpanData(name="content_filter", triggered=False))
+
+    processor.on_span_start(span)
+    span.span_data.triggered = triggered
+    processor.on_span_end(span)
+
+    finished_span = span_exporter.get_finished_spans()[0]
+    assert finished_span.name == "run_guardrail content_filter"
+    assert finished_span.attributes == {
+        "gen_ai.operation.name": "run_guardrail",
+        "gen_ai.guardrail.component.name": "content_filter",
+        "gen_ai.provider.name": "openai",
+        "gen_ai.guardrail.verdict.type": verdict,
+    }
+
+
 def test_function_span_creates_tool_invocation_and_sets_provider_metric() -> (
     None
 ):
@@ -344,6 +376,24 @@ def test_tool_span_error_sets_error_status_and_type(
     assert tool_span.attributes["error.type"] == "_OTHER"
 
 
+def test_guardrail_span_error_sets_error_status_and_type(
+    tracer_provider: TracerProvider,
+    span_exporter: InMemorySpanExporter,
+) -> None:
+    handler = TelemetryHandler(tracer_provider=tracer_provider)
+    processor = GenAITracingProcessor(handler, provider="openai")
+    span = _Span(GuardrailSpanData(name="content_filter", triggered=False))
+    span.error = {"message": "Error running guardrail", "data": {}}
+
+    processor.on_span_start(span)
+    processor.on_span_end(span)
+
+    (guardrail_span,) = span_exporter.get_finished_spans()
+    assert guardrail_span.status.status_code is StatusCode.ERROR
+    assert guardrail_span.attributes is not None
+    assert guardrail_span.attributes["error.type"] == "_OTHER"
+
+
 def test_agent_span_error_sets_error_status_and_type(
     tracer_provider: TracerProvider,
     span_exporter: InMemorySpanExporter,

util/opentelemetry-util-genai/.changelog/+run-guardrail-span.added

@@ -0,0 +1 @@
+Add ``GuardrailInvocation`` for recording semantic-convention ``run_guardrail`` spans.

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_guardrail_invocation.py

@@ -0,0 +1,106 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from opentelemetry._logs import Logger
+from opentelemetry.semconv._incubating.attributes.gen_ai_attributes import (
+    GEN_AI_OPERATION_NAME,
+    GEN_AI_PROVIDER_NAME,
+)
+from opentelemetry.trace import SpanKind, Tracer
+from opentelemetry.util.genai._invocation import Error, GenAIInvocation
+from opentelemetry.util.genai.completion_hook import CompletionHook
+from opentelemetry.util.genai.metrics import InvocationMetricsRecorder
+from opentelemetry.util.types import AttributeValue
+
+# semconv-genai#427 (unreleased)
+# TODO: switch to the semconv module once #427 merges.
+_GEN_AI_OPERATION_NAME_RUN_GUARDRAIL = "run_guardrail"
+# semconv-genai#427 (unreleased)
+# TODO: switch to the semconv module once #427 merges.
+_GEN_AI_GUARDRAIL_COMPONENT_NAME = "gen_ai.guardrail.component.name"
+# semconv-genai#427 (unreleased)
+# TODO: switch to the semconv module once #427 merges.
+_GEN_AI_GUARDRAIL_VERDICT_TYPE = "gen_ai.guardrail.verdict.type"
+# semconv-genai#427 (unreleased)
+# TODO: switch to the semconv module once #427 merges.
+_GEN_AI_GUARDRAIL_TARGET_TYPE = "gen_ai.guardrail.target.type"
+
+
+class GuardrailInvocation(GenAIInvocation):
+    """Represents a guardrail invocation for run_guardrail span tracking.
+
+    Use handler.guardrail(name) rather than constructing this directly.
+
+    Reference: https://github.com/open-telemetry/semantic-conventions-genai/pull/427
+
+    Semantic convention attributes for run_guardrail spans:
+    - gen_ai.operation.name: "run_guardrail"
+    - gen_ai.guardrail.component.name: Name of the guardrail
+    - gen_ai.provider.name: Name of the GenAI provider
+    - gen_ai.guardrail.verdict.type: "deny" if triggered, otherwise "allow"
+    - gen_ai.guardrail.target.type: "input" or "output". Required by
+      semconv-genai#427 and must be supplied by instrumentations that know the
+      guardrail direction.
+    """
+
+    def __init__(
+        self,
+        tracer: Tracer,
+        metrics_recorder: InvocationMetricsRecorder,
+        logger: Logger,
+        completion_hook: CompletionHook,
+        name: str,
+        *,
+        provider: str,
+        target_type: str | None = None,
+    ) -> None:
+        """Use handler.guardrail(name) instead of calling this directly."""
+        operation_name = _GEN_AI_OPERATION_NAME_RUN_GUARDRAIL
+        super().__init__(
+            tracer,
+            metrics_recorder,
+            logger,
+            completion_hook,
+            operation_name=operation_name,
+            span_name=f"{operation_name} {name}" if name else operation_name,
+            span_kind=SpanKind.INTERNAL,
+        )
+        self._name: str = name
+        self._provider: str = provider
+        self.triggered: bool = False
+        self.target_type: str | None = target_type
+        self._start(self._get_start_attributes())
+
+    def _get_start_attributes(self) -> dict[str, AttributeValue]:
+        """Return sampling-relevant attributes available at span creation time."""
+        return {
+            GEN_AI_OPERATION_NAME: self._operation_name,
+            _GEN_AI_GUARDRAIL_COMPONENT_NAME: self._name,
+            GEN_AI_PROVIDER_NAME: self._provider,
+        }
+
+    def _get_metric_attributes(self) -> dict[str, AttributeValue]:
+        attrs: dict[str, AttributeValue] = {
+            GEN_AI_OPERATION_NAME: self._operation_name,
+            GEN_AI_PROVIDER_NAME: self._provider,
+        }
+        attrs.update(self.metric_attributes)
+        return attrs
+
+    def _apply_finish(self, error: Error | None = None) -> None:
+        if error is not None:
+            self._apply_error_attributes(error)
+        optional_attrs = (
+            (_GEN_AI_GUARDRAIL_TARGET_TYPE, self.target_type),
+        )
+        attributes: dict[str, AttributeValue] = {
+            _GEN_AI_GUARDRAIL_VERDICT_TYPE: (
+                "deny" if self.triggered else "allow"
+            ),
+            **{key: value for key, value in optional_attrs if value is not None},
+        }
+        attributes.update(self.attributes)
+        self.span.set_attributes(attributes)
+        self._metrics_recorder.record(self)

util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py

@@ -58,6 +58,7 @@
 from opentelemetry.util.genai.invocation import (
     EmbeddingInvocation,
     FetchResponseInvocation,
+    GuardrailInvocation,
     InferenceInvocation,
     RetrievalInvocation,
     ToolInvocation,
@@ -435,6 +436,34 @@ def tool(
             tool_description=tool_description,
         )
 
+    def guardrail(
+        self,
+        name: str,
+        *,
+        provider: str,
+        target_type: str | None = None,
+    ) -> GuardrailInvocation:
+        """Returns a Guardrail invocation. Starts span when called.
+
+        Returned object can be used as a ContextManager which automatically calls `stop` or `fail`
+        to finalize the span upon exiting. If not used as a ContextManager, the caller is
+        responsible for calling `stop` or `fail` to finalize the span.
+
+        ``target_type`` is required by semconv-genai#427 and must be supplied
+        by instrumentations that know the guardrail direction.
+
+        Only set data attributes on the invocation object, do not modify the span or context.
+        """
+        return GuardrailInvocation(
+            self._tracer,
+            self._metrics_recorder,
+            self._logger,
+            self._completion_hook,
+            name,
+            provider=provider,
+            target_type=target_type,
+        )
+
     def start_invoke_local_agent(
         self,
         *,

util/opentelemetry-util-genai/src/opentelemetry/util/genai/invocation.py

@@ -22,6 +22,7 @@
 from opentelemetry.util.genai._fetch_response_invocation import (
     FetchResponseInvocation,
 )
+from opentelemetry.util.genai._guardrail_invocation import GuardrailInvocation
 from opentelemetry.util.genai._inference_invocation import InferenceInvocation
 from opentelemetry.util.genai._invocation import (
     ContextToken,
@@ -39,6 +40,7 @@
     "Error",
     "FetchResponseInvocation",
     "GenAIInvocation",
+    "GuardrailInvocation",
     "InferenceInvocation",
     "RetrievalInvocation",
     "ToolInvocation",

util/opentelemetry-util-genai/tests/test_handler_guardrail.py

@@ -0,0 +1,54 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
+    InMemorySpanExporter,
+)
+from opentelemetry.trace import SpanKind
+from opentelemetry.util.genai.handler import TelemetryHandler
+
+
+def _make_span_exporter_and_handler() -> (
+    tuple[InMemorySpanExporter, TelemetryHandler]
+):
+    span_exporter = InMemorySpanExporter()
+    tracer_provider = TracerProvider()
+    tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
+    return span_exporter, TelemetryHandler(tracer_provider=tracer_provider)
+
+
+def test_guardrail_span_attributes_and_name() -> None:
+    span_exporter, handler = _make_span_exporter_and_handler()
+    invocation = handler.guardrail(
+        "content_filter",
+        provider="openai",
+    )
+    invocation.stop()
+
+    span = span_exporter.get_finished_spans()[0]
+    assert span.name == "run_guardrail content_filter"
+    assert span.kind == SpanKind.INTERNAL
+    assert span.attributes == {
+        "gen_ai.operation.name": "run_guardrail",
+        "gen_ai.guardrail.component.name": "content_filter",
+        "gen_ai.provider.name": "openai",
+        "gen_ai.guardrail.verdict.type": "allow",
+    }
+    assert "gen_ai.guardrail.target.type" not in span.attributes
+
+
+def test_guardrail_target_type_and_deny_verdict() -> None:
+    span_exporter, handler = _make_span_exporter_and_handler()
+    invocation = handler.guardrail(
+        "jailbreak_filter",
+        provider="openai",
+        target_type="input",
+    )
+    invocation.triggered = True
+    invocation.stop()
+
+    span = span_exporter.get_finished_spans()[0]
+    assert span.attributes["gen_ai.guardrail.verdict.type"] == "deny"
+    assert span.attributes["gen_ai.guardrail.target.type"] == "input"