gen-ai: add security guardian (apply_guardrail) span + finding event

[nagkumar91]

Motivation

GenAI semantic conventions cover model, agent, and tool operations, but they don’t provide a vendor-neutral way to observe security guardian/
guardrail evaluations (allow/deny/modify decisions) and the specific security findings produced during those evaluations. This limits
auditability, incident investigation, and cross-provider correlation for systems using guardrails across different vendors and frameworks.

What this PR adds

• Adds apply_guardrail to the gen_ai.operation.name enum for guardrail/guardian evaluations.
• Adds new attributes under gen_ai.guardian.* and gen_ai.security.* to describe:
  • Guardian identity (gen_ai.guardian.*)
  • Decision outcomes (gen_ai.security.decision.*)
  • Target being evaluated (gen_ai.security.target.*)
  • Findings and policy context (gen_ai.security.risk.*, gen_ai.security.policy.*)
  • Opt-in content capture (gen_ai.security.content.*)
• Note: gen_ai.security.risk.category is a free-form string with suggested values aligned with OWASP LLM Top 10 2025.
• Adds a new span: span.gen_ai.apply_guardrail.internal (guardian evaluation).
• Adds a new event: gen_ai.security.finding (individual findings under a guardian evaluation).
• Adds documentation: docs/gen-ai/gen-ai-security.md (linked from docs/gen-ai/README.md).

References

• OTel GenAI semantic conventions: https://opentelemetry.io/docs/specs/semconv/gen-ai/
• OWASP Agent Observability Standard (decision events / allow-deny-modify model): https://aos.owasp.org/spec/trace/events/
• OWASP Agent Observability Standard (mapping guidance to OpenTelemetry): https://aos.owasp.org/spec/trace/extend_opentelemetry/
• OWASP LLM Top 10 (2025): https://genai.owasp.org/llm-top-10/

Prototypes / instrumentation links

• Story scenarios + trace viewer: https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/stories/README.md (https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/stories/run_and_view.py, https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/stories/TRACE_COVERAGE.md)
• Story files: https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/stories/story_4_enterprise_rag_access_control.py, https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/stories/story_5_multi_tenant.py, https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/stories/story_7_multi_agent.py, https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/stories/story_10_progressive_jailbreak.py, https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/stories/story_11_guardian_error_handling.py
• Trace viewer internals: https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/stories/trace_viewer.py, https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/stories/trace_retriever.py
• Story runner CLI: https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/stories/story_runner.py
• Prototype overview + run instructions: https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/README.md
• OTEL bootstrap + exporter wiring: https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/otel_bootstrap.py
• Guardian span + event helpers: https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/otel_guardian_utils.py
• Optional realism helpers: https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/demo_chat.py, https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/demo_tools.py
• Original single-file prototype: https://github.com/open-telemetry/semantic-conventions/blob/24f9aa473e51f4f432819e834fd9617d5acb2563/prototype/genai_guardrail_instrumentation_prototype.py

Tests

• make table-generation registry-generation
• make markdown-toc
• make SED=sed check-policies (macOS note: the repo defaults to gsed)

Changelog

This is user-facing (new conventions). Add a .chloggen/*.yaml entry with component: gen-ai, or apply the “Skip Changelog” label if
maintainers agree it’s not required for this proposal stage.

[adityamehra]

@nagkumar91 We have a similar use-case and when a security incident happens for a chat span we create a new span as a chat span and add an attributed called gen_ai.security.event_id. The value for this attribute can either be in the response body of the inspection call, which is separate from the actual LLM call, or can be in the response header when inspection happens along with the LLM call. Is it possible to add support for this attribute in here? Thanks!

Here's the sample of how we add it as of now - https://github.com/signalfx/splunk-otel-python-contrib/tree/main/instrumentation-genai/opentelemetry-instrumentation-aidefense#trace-integration

[adityamehra]

Also, it will be great if we can have another entry in the otel-genai-util for this new span type like we have for chat span - https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py#L96. Or probably this new type can extend the LLMInvocation type

[adityamehra]

Can we add an attribute called gen_ai.security.event_id?

[nagkumar91]

The event being proposed would be a gen_ai.security.finding

Apply guardrail span will have these for IDs:

• gen_ai.guardian.id
• gen_ai.security.target.id
• gen_ai.security.policy.id

Would any of those fit your need?

[adityamehra]

Would this be better as an event (security finding event as proposed in this span)? Wondering why its a chat span?

Currently, the domain team is using event_id and it's as per their requirement. Also, in our case the event is generated elsewhere and not instrumentation side. We used chat span to use existing types in the genai-utils for now and manage span life cycle using it.

[nagkumar91]

@nagkumar91 We have a similar use-case and when a security incident happens for a chat span we create a new span as a chat span and add an attributed called gen_ai.security.event_id. The value for this attribute can either be in the response body of the inspection call, which is separate from the actual LLM call, or can be in the response header when inspection happens along with the LLM call. Is it possible to add support for this attribute in here? Thanks!

Here's the sample of how we add it as of now - https://github.com/signalfx/splunk-otel-python-contrib/tree/main/instrumentation-genai/opentelemetry-instrumentation-aidefense#trace-integration

Would this be better as an event (security finding event as proposed in this span)? Wondering why its a chat span?