diff --git a/.chloggen/gen-ai-security-guardian.yaml b/.chloggen/gen-ai-security-guardian.yaml new file mode 100644 index 0000000000..6a357d8416 --- /dev/null +++ b/.chloggen/gen-ai-security-guardian.yaml @@ -0,0 +1,6 @@ +change_type: enhancement +component: gen-ai +note: "Add semantic conventions for GenAI security guardian evaluations (`apply_guardrail` span and `gen_ai.security.finding` event)." +issues: [3233] +subtext: | + Adds new `gen_ai.guardian.*` and `gen_ai.security.*` attributes for vendor-neutral guardrail/guardian decisions and findings. diff --git a/docs/gen-ai/README.md b/docs/gen-ai/README.md index d509d65215..1467c9bc2c 100644 --- a/docs/gen-ai/README.md +++ b/docs/gen-ai/README.md @@ -34,6 +34,7 @@ Semantic conventions for Generative AI operations are defined for the following * [Metrics](gen-ai-metrics.md): Semantic Conventions for Generative AI operations - *metrics*. * [Model spans](gen-ai-spans.md): Semantic Conventions for Generative AI model operations - *spans*. * [Agent spans](gen-ai-agent-spans.md): Semantic Conventions for Generative AI agent operations - *spans*. +* [Security](gen-ai-security.md): Semantic Conventions for GenAI security guardian evaluations. Technology specific semantic conventions are defined for the following GenAI system: diff --git a/docs/gen-ai/anthropic.md b/docs/gen-ai/anthropic.md index 1083e874ba..5466fd70b7 100644 --- a/docs/gen-ai/anthropic.md +++ b/docs/gen-ai/anthropic.md @@ -211,6 +211,7 @@ populating this attribute. | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/gen-ai/aws-bedrock.md b/docs/gen-ai/aws-bedrock.md index 6abb4a0830..c6d96faaac 100644 --- a/docs/gen-ai/aws-bedrock.md +++ b/docs/gen-ai/aws-bedrock.md @@ -235,6 +235,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/gen-ai/azure-ai-inference.md b/docs/gen-ai/azure-ai-inference.md index f7abfcce7a..23718a60c0 100644 --- a/docs/gen-ai/azure-ai-inference.md +++ b/docs/gen-ai/azure-ai-inference.md @@ -236,6 +236,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/gen-ai/gen-ai-agent-spans.md b/docs/gen-ai/gen-ai-agent-spans.md index f235d084c2..ea70dd227b 100644 --- a/docs/gen-ai/gen-ai-agent-spans.md +++ b/docs/gen-ai/gen-ai-agent-spans.md @@ -137,6 +137,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -398,6 +399,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -550,6 +552,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md index bb2c5c7cc1..c78d85bb1e 100644 --- a/docs/gen-ai/gen-ai-events.md +++ b/docs/gen-ai/gen-ai-events.md @@ -207,6 +207,7 @@ populating this attribute. | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md index 706259dabb..f300428203 100644 --- a/docs/gen-ai/gen-ai-metrics.md +++ b/docs/gen-ai/gen-ai-metrics.md @@ -121,6 +121,7 @@ applicable `aws.bedrock.*` attributes and are not expected to include | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -242,6 +243,7 @@ Instrumentations SHOULD document the list of errors they report. | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -343,6 +345,7 @@ applicable `aws.bedrock.*` attributes and are not expected to include | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -444,6 +447,7 @@ applicable `aws.bedrock.*` attributes and are not expected to include | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -563,6 +567,7 @@ Instrumentations SHOULD document the list of errors they report. | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -669,6 +674,7 @@ applicable `aws.bedrock.*` attributes and are not expected to include | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -774,6 +780,7 @@ applicable `aws.bedrock.*` attributes and are not expected to include | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/gen-ai/gen-ai-security.md b/docs/gen-ai/gen-ai-security.md new file mode 100644 index 0000000000..1ed5a1d9b4 --- /dev/null +++ b/docs/gen-ai/gen-ai-security.md @@ -0,0 +1,291 @@ + + +# Semantic conventions for GenAI security operations + +**Status**: [Development][DocumentStatus] + + + +- [Spans](#spans) + - [Apply guardrail](#apply-guardrail) +- [Events](#events) + - [Event: `gen_ai.security.finding`](#event-gen_aisecurityfinding) + + + +GenAI systems and agent frameworks commonly use security guardians (sometimes called guardrails) to +evaluate content and actions for risks such as prompt injection, sensitive information disclosure, or +policy violations. + +These semantic conventions define: + +- A span that represents a single guardian evaluation. +- An event that captures individual security findings emitted during that evaluation. + +For implementation guidance, examples, and design rationale, see the +[non-normative implementation guide](https://gist.github.com/nagkumar91/95efa05449c72b4c95958190f26f13ba). + +## Spans + +### Apply guardrail + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +Describes a security guardian evaluation. + +`gen_ai.operation.name` SHOULD be `apply_guardrail`. + +**Span name** SHOULD be `apply_guardrail {gen_ai.guardian.name} {gen_ai.security.target.type}`. +When `gen_ai.guardian.name` is not available, it SHOULD be `apply_guardrail {gen_ai.security.target.type}`. + +Guardian spans SHOULD be children of the operation span they are protecting (for example, +`span.gen_ai.inference.client` or `span.gen_ai.execute_tool.internal`). + +Multiple guardian spans MAY exist under a single operation span if multiple guardians are chained. + +**Span kind** SHOULD be `INTERNAL`. + +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. + +**Attributes:** + +| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | +| --- | --- | --- | --- | --- | --- | +| [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `text_completion` | +| [`gen_ai.security.decision.type`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The decision made by the security guardian. | `allow`; `deny`; `modify` | +| [`gen_ai.security.target.type`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The type of content or action the guardrail is applied to. [2] | `tool_call`; `llm_input`; `llm_output`; `tool_definition` | +| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` if the operation ended in an error | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | +| [`gen_ai.agent.id`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` when applicable | string | The unique identifier of the GenAI agent. | `asst_5j66UpCpwteGg4YSxUnt7lPY` | +| [`gen_ai.conversation.id`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` when available | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. | `conv_5j66UpCpwteGg4YSxUnt7lPY` | +| [`gen_ai.guardian.id`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available | string | The unique identifier of the security guardian (the evaluating service or component). [4] | `guard_abc123`; `content-filter-v2`; `custom-guardian-001` | +| [`gen_ai.security.content.input.hash`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if correlation is needed and available | string | Hash of the input content for forensic correlation. [5] | `sha256:a3f2b8c9...` | +| [`gen_ai.security.content.modified`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if `gen_ai.security.decision.type` is `modify` | boolean | Whether the content was modified by the guardrail (e.g., redacted, sanitized, rewritten). | `true`; `false` | +| [`gen_ai.security.decision.reason`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [6] | string | Human-readable explanation for the security decision. [7] | `PII detected in output, masked before delivery`; `Prompt injection attempt denied`; `Action exceeds agent permission scope` | +| [`gen_ai.security.external_event_id`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [8] | string | External correlation identifier for security events. [9] | `evt_abc123`; `incident-2024-001`; `sec-finding-xyz` | +| [`gen_ai.security.policy.id`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if a policy triggered the decision | string | Identifier of the policy that triggered the decision. | `policy_pii_v2`; `deny-topic-financial-advice`; `org-compliance-001` | +| [`gen_ai.security.target.id`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available | string | Identifier of the specific target the guardrail is applied to. [10] | `call_xyz789`; `tool-123`; `mem_abc456` | +| [`gen_ai.guardian.name`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Human-readable name of the guardian (the evaluating service or component). [11] | `Azure Content Safety`; `Bedrock Guardrails`; `Custom PII Filter` | +| [`gen_ai.guardian.provider.name`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The provider or vendor of the guardian service. [12] | `azure.ai.content_safety`; `aws.bedrock`; `gcp.model_armor` | +| [`gen_ai.guardian.version`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Version of the guardian service or component. [13] | `1.0.0`; `2024-05-01`; `v2` | +| [`gen_ai.security.decision.code`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | Numeric code for the security decision (provider-specific). | `112`; `403`; `5001` | +| [`gen_ai.security.policy.name`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Human-readable name of the triggered policy. | `PII Protection Policy`; `Financial Advice Restriction` | +| [`gen_ai.security.policy.version`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Version of the policy that triggered the decision. | `1.0`; `2024-05-01` | +| [`gen_ai.security.content.input.value`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | any | The input content that was evaluated by the guardian. [14] | `Send an email to customer@example.com` | +| [`gen_ai.security.content.output.value`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | any | The output content after guardian processing (if modified). [15] | `Send an email to [REDACTED]` | + +**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. + +**[2] `gen_ai.security.target.type`:** This attribute is free-form to accommodate provider-specific, +organization-specific, or emerging target types. + +Suggested values include: + +- `llm_input`: Prompt or messages being sent to the model. +- `llm_output`: Response or messages returned from the model. +- `tool_call`: Tool execution request (tool call invocation). +- `tool_definition`: Tool definition or schema (tool declaration). +- `memory_store`: Data being written to memory. +- `memory_retrieve`: Data being read from memory. +- `knowledge_query`: Knowledge/RAG query being sent. +- `knowledge_result`: Knowledge/RAG results being returned. +- `message`: Conversation message (user, assistant, tool). + +**[3] `error.type`:** The `error.type` SHOULD match the error code returned by the guardian or the client library, +the canonical name of exception that occurred, or another low-cardinality error identifier. +Instrumentations SHOULD document the list of errors they report. + +**[4] `gen_ai.guardian.id`:** This identifies the service, component, or library performing the security +evaluation - NOT the policy or configuration being applied. + +For provider-specific guardrail/policy configuration identifiers (e.g., +AWS Bedrock guardrail ARN, Azure Content Safety blocklist ID), use +`gen_ai.security.policy.id` instead. + +Example mapping: + +- Guardian: The evaluation service (e.g., "bedrock_guardrail_service", "azure_content_safety") +- Policy: The specific configuration (e.g., "arn:aws:bedrock:us-east-1:123456789:guardrail/abc123") + +**[5] `gen_ai.security.content.input.hash`:** Use when full content capture is not desired but correlation is needed. Instrumentations SHOULD document the algorithm and any salting/HMAC approach used. + +**[6] `gen_ai.security.decision.reason`:** if `gen_ai.security.decision.type` is not `allow` and a reason is available + +**[7] `gen_ai.security.decision.reason`:** The value SHOULD be low-cardinality and MUST NOT contain sensitive user content or other high-risk data. + +**[8] `gen_ai.security.external_event_id`:** if correlation with external security systems is needed + +**[9] `gen_ai.security.external_event_id`:** This attribute links the telemetry to an external security event record +in systems such as SIEM, incident management, or security dashboards. + +The value typically comes from the response of an external security +inspection service or may be included in response headers when inspection +happens alongside the LLM call. + +Use this when correlation with external security systems is required +beyond what `gen_ai.security.policy.id` provides. + +**[10] `gen_ai.security.target.id`:** For example, a tool call identifier, request identifier, or memory entry identifier, if applicable. + +**[11] `gen_ai.guardian.name`:** This identifies the security evaluation service or component, not the policy name. For policy names, use `gen_ai.security.policy.name`. + +**[12] `gen_ai.guardian.provider.name`:** This identifies the guardrail provider, which may differ from the inference provider (`gen_ai.provider.name`). For example, an agent may use OpenAI for inference and Azure AI Content Safety for content filtering in the same trace. + +**[13] `gen_ai.guardian.version`:** This is the version of the evaluating service/component, not the policy version. For policy versions, use `gen_ai.security.policy.version`. + +**[14] `gen_ai.security.content.input.value`:** + +> [!WARNING] +> This attribute may contain sensitive information including user/PII +> data. Instrumentations SHOULD NOT capture this by default. Enable via +> opt-in configuration only. + +This attribute MAY be truncated. For correlation without full content, +consider `gen_ai.security.content.input.hash`. + +**[15] `gen_ai.security.content.output.value`:** + +> [!WARNING] +> This attribute may contain sensitive information. Instrumentations +> SHOULD NOT capture this by default. Enable via opt-in configuration +> only. + +For `modify` decisions, this MAY contain the sanitized/redacted result. + +--- + +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --- | --- | --- | +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +--- + +`gen_ai.guardian.provider.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --- | --- | --- | +| `aws.bedrock` | [AWS Bedrock Guardrails](https://aws.amazon.com/bedrock/guardrails/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.content_safety` | [Azure AI Content Safety](https://azure.microsoft.com/products/ai-services/ai-content-safety/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.model_armor` | [GCP Model Armor](https://cloud.google.com/security/products/model-armor) | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | +| `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | +| `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | +| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) | +| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) | +| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | +| `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![Development](https://img.shields.io/badge/-development-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`gen_ai.security.decision.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --- | --- | --- | +| `allow` | Request permitted to proceed without modification. | ![Development](https://img.shields.io/badge/-development-blue) | +| `audit` | Request logged for audit purposes only, no enforcement. | ![Development](https://img.shields.io/badge/-development-blue) | +| `deny` | Request denied and operation halted. | ![Development](https://img.shields.io/badge/-development-blue) | +| `modify` | Request permitted with modifications (redaction, sanitization). | ![Development](https://img.shields.io/badge/-development-blue) | +| `warn` | Request permitted but flagged for review. | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + +## Events + +### Event: `gen_ai.security.finding` + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +The event name MUST be `gen_ai.security.finding`. + +Reports a specific security finding detected during guardian evaluation. + +Multiple findings MAY be emitted for a single guardian span. + +Events SHOULD be parented to the `span.gen_ai.apply_guardrail.internal` span when possible. + +**Attributes:** + +| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | +| --- | --- | --- | --- | --- | --- | +| [`gen_ai.security.risk.category`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The category of security risk detected. [1] | `prompt_injection`; `sensitive_info_disclosure`; `jailbreak`; `custom:financial_advice_violation`; `azure:hate_speech` | +| [`gen_ai.security.risk.severity`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The severity level of the detected risk. | `low`; `medium`; `high`; `critical` | +| [`gen_ai.security.policy.id`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if triggered by a specific policy | string | Identifier of the policy that triggered the decision. | `policy_pii_v2`; `deny-topic-financial-advice`; `org-compliance-001` | +| [`gen_ai.security.policy.name`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Human-readable name of the triggered policy. | `PII Protection Policy`; `Financial Advice Restriction` | +| [`gen_ai.security.policy.version`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Version of the policy that triggered the decision. | `1.0`; `2024-05-01` | +| [`gen_ai.security.risk.metadata`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string[] | Non-content metadata about the detected risk. [2] | `["field:bcc", "pattern:email"]`; `["count:2", "position:output.content"]` | +| [`gen_ai.security.risk.score`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | double | Numeric risk/confidence score (0.0 to 1.0). | `0.85`; `0.95`; `0.42` | + +**[1] `gen_ai.security.risk.category`:** This attribute is free-form to accommodate provider-specific, +organization-specific, or emerging risk categories. + +Suggested values aligned with OWASP LLM Top 10 2025 include: + +- `prompt_injection` (LLM01) +- `sensitive_info_disclosure` (LLM02) +- `supply_chain` (LLM03) +- `data_and_model_poisoning` (LLM04) +- `improper_output_handling` (LLM05) +- `excessive_agency` (LLM06) +- `system_prompt_leakage` (LLM07) +- `vector_and_embedding_weaknesses` (LLM08) +- `misinformation` (LLM09) +- `unbounded_consumption` (LLM10) + +Instrumentations MAY use additional values when appropriate, for +example: `jailbreak`, `toxicity`, `pii`, `custom:*`, `azure:*`. + +**[2] `gen_ai.security.risk.metadata`:** + +> [!WARNING] +> This attribute MUST NOT contain sensitive user content, PII, or other +> high-risk data. + +Example values include: + +- Field identifiers: `field:bcc`, `parameter:query` +- Pattern types: `pattern:ssn`, `pattern:credit_card` +- Counts: `count:3` +- Positions: `position:input[0].content` + +--- + +`gen_ai.security.risk.severity` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --- | --- | --- | +| `critical` | Critical severity risk requiring immediate action. | ![Development](https://img.shields.io/badge/-development-blue) | +| `high` | High severity risk. | ![Development](https://img.shields.io/badge/-development-blue) | +| `low` | Low severity risk. | ![Development](https://img.shields.io/badge/-development-blue) | +| `medium` | Medium severity risk. | ![Development](https://img.shields.io/badge/-development-blue) | +| `none` | No risk detected. | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index fa67bd82a6..d893400148 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -249,6 +249,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -395,6 +396,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -529,6 +531,7 @@ Each document object SHOULD contain at least the following properties: | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -662,6 +665,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/gen-ai/mcp.md b/docs/gen-ai/mcp.md index 372c903023..3b856d091f 100644 --- a/docs/gen-ai/mcp.md +++ b/docs/gen-ai/mcp.md @@ -244,6 +244,7 @@ deserialize it to an object. When recorded on spans, it MAY be recorded as a JSO | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -404,6 +405,7 @@ It SHOULD be set to `pipe` if the transport is stdio. | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -543,6 +545,7 @@ It SHOULD be set to `pipe` if the transport is stdio. | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -674,6 +677,7 @@ It SHOULD be set to `pipe` if the transport is stdio. | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/gen-ai/openai.md b/docs/gen-ai/openai.md index dc8d82df57..584faaa153 100644 --- a/docs/gen-ai/openai.md +++ b/docs/gen-ai/openai.md @@ -239,6 +239,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/registry/attributes/gen-ai.md b/docs/registry/attributes/gen-ai.md index b7b4f0926d..f6f8c21e5c 100644 --- a/docs/registry/attributes/gen-ai.md +++ b/docs/registry/attributes/gen-ai.md @@ -26,14 +26,18 @@ This document defines the attributes used to describe telemetry in the context o | `gen_ai.evaluation.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | The name of the evaluation metric used for the GenAI response. | `Relevance`; `IntentResolution` | | `gen_ai.evaluation.score.label` | ![Development](https://img.shields.io/badge/-development-blue) | string | Human readable label for evaluation. [2] | `relevant`; `not_relevant`; `correct`; `incorrect`; `pass`; `fail` | | `gen_ai.evaluation.score.value` | ![Development](https://img.shields.io/badge/-development-blue) | double | The evaluation score returned by the evaluator. | `4.0` | -| `gen_ai.input.messages` | ![Development](https://img.shields.io/badge/-development-blue) | any | The chat history provided to the model as an input. [3] | [
  {
    "role": "user",
    "parts": [
      {
        "type": "text",
        "content": "Weather in Paris?"
      }
    ]
  },
  {
    "role": "assistant",
    "parts": [
      {
        "type": "tool_call",
        "id": "call_VSPygqKTWdrhaFErNvMV18Yl",
        "name": "get_weather",
        "arguments": {
          "location": "Paris"
        }
      }
    ]
  },
  {
    "role": "tool",
    "parts": [
      {
        "type": "tool_call_response",
        "id": " call_VSPygqKTWdrhaFErNvMV18Yl",
        "result": "rainy, 57°F"
      }
    ]
  }
] | -| `gen_ai.operation.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | The name of the operation being performed. [4] | `chat`; `generate_content`; `text_completion` | -| `gen_ai.output.messages` | ![Development](https://img.shields.io/badge/-development-blue) | any | Messages returned by the model where each message represents a specific model response (choice, candidate). [5] | [
  {
    "role": "assistant",
    "parts": [
      {
        "type": "text",
        "content": "The weather in Paris is currently rainy with a temperature of 57°F."
      }
    ],
    "finish_reason": "stop"
  }
] | -| `gen_ai.output.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | Represents the content type requested by the client. [6] | `text`; `json`; `image` | +| `gen_ai.guardian.id` | ![Development](https://img.shields.io/badge/-development-blue) | string | The unique identifier of the security guardian (the evaluating service or component). [3] | `guard_abc123`; `content-filter-v2`; `custom-guardian-001` | +| `gen_ai.guardian.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | Human-readable name of the guardian (the evaluating service or component). [4] | `Azure Content Safety`; `Bedrock Guardrails`; `Custom PII Filter` | +| `gen_ai.guardian.provider.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | The provider or vendor of the guardian service. [5] | `azure.ai.content_safety`; `aws.bedrock`; `gcp.model_armor` | +| `gen_ai.guardian.version` | ![Development](https://img.shields.io/badge/-development-blue) | string | Version of the guardian service or component. [6] | `1.0.0`; `2024-05-01`; `v2` | +| `gen_ai.input.messages` | ![Development](https://img.shields.io/badge/-development-blue) | any | The chat history provided to the model as an input. [7] | [
  {
    "role": "user",
    "parts": [
      {
        "type": "text",
        "content": "Weather in Paris?"
      }
    ]
  },
  {
    "role": "assistant",
    "parts": [
      {
        "type": "tool_call",
        "id": "call_VSPygqKTWdrhaFErNvMV18Yl",
        "name": "get_weather",
        "arguments": {
          "location": "Paris"
        }
      }
    ]
  },
  {
    "role": "tool",
    "parts": [
      {
        "type": "tool_call_response",
        "id": " call_VSPygqKTWdrhaFErNvMV18Yl",
        "result": "rainy, 57°F"
      }
    ]
  }
] | +| `gen_ai.operation.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | The name of the operation being performed. [8] | `chat`; `generate_content`; `text_completion` | +| `gen_ai.output.messages` | ![Development](https://img.shields.io/badge/-development-blue) | any | Messages returned by the model where each message represents a specific model response (choice, candidate). [9] | [
  {
    "role": "assistant",
    "parts": [
      {
        "type": "text",
        "content": "The weather in Paris is currently rainy with a temperature of 57°F."
      }
    ],
    "finish_reason": "stop"
  }
] | +| `gen_ai.output.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | Represents the content type requested by the client. [10] | `text`; `json`; `image` | | `gen_ai.prompt.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | The name of the prompt that uniquely identifies it. | `analyze-code` | -| `gen_ai.provider.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | The Generative AI provider as identified by the client or server instrumentation. [7] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | +| `gen_ai.provider.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | The Generative AI provider as identified by the client or server instrumentation. [11] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | | `gen_ai.request.choice.count` | ![Development](https://img.shields.io/badge/-development-blue) | int | The target number of candidate completions to return. | `3` | -| `gen_ai.request.encoding_formats` | ![Development](https://img.shields.io/badge/-development-blue) | string[] | The encoding formats requested in an embeddings operation, if specified. [8] | `["base64"]`; `["float", "binary"]` | +| `gen_ai.request.encoding_formats` | ![Development](https://img.shields.io/badge/-development-blue) | string[] | The encoding formats requested in an embeddings operation, if specified. [12] | `["base64"]`; `["float", "binary"]` | | `gen_ai.request.frequency_penalty` | ![Development](https://img.shields.io/badge/-development-blue) | double | The frequency penalty setting for the GenAI request. | `0.1` | | `gen_ai.request.max_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The maximum number of tokens the model generates for a request. | `100` | | `gen_ai.request.model` | ![Development](https://img.shields.io/badge/-development-blue) | string | The name of the GenAI model a request is being made to. | `gpt-4` | @@ -46,28 +50,63 @@ This document defines the attributes used to describe telemetry in the context o | `gen_ai.response.finish_reasons` | ![Development](https://img.shields.io/badge/-development-blue) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`; `["stop", "length"]` | | `gen_ai.response.id` | ![Development](https://img.shields.io/badge/-development-blue) | string | The unique identifier for the completion. | `chatcmpl-123` | | `gen_ai.response.model` | ![Development](https://img.shields.io/badge/-development-blue) | string | The name of the model that generated the response. | `gpt-4-0613` | -| `gen_ai.retrieval.documents` | ![Development](https://img.shields.io/badge/-development-blue) | any | The documents retrieved. [9] | [
  {
    "id": "doc_123",
    "score": 0.95
  },
  {
    "id": "doc_456",
    "score": 0.87
  },
  {
    "id": "doc_789",
    "score": 0.82
  }
] | -| `gen_ai.retrieval.query.text` | ![Development](https://img.shields.io/badge/-development-blue) | string | The query text used for retrieval. [10] | `What is the capital of France?`; `weather in Paris` | -| `gen_ai.system_instructions` | ![Development](https://img.shields.io/badge/-development-blue) | any | The system message or instructions provided to the GenAI model separately from the chat history. [11] | [
  {
    "type": "text",
    "content": "You are an Agent that greet users, always use greetings tool to respond"
  }
]; [
  {
    "type": "text",
    "content": "You are a language translator."
  },
  {
    "type": "text",
    "content": "Your mission is to translate text in English to French."
  }
] | +| `gen_ai.retrieval.documents` | ![Development](https://img.shields.io/badge/-development-blue) | any | The documents retrieved. [13] | [
  {
    "id": "doc_123",
    "score": 0.95
  },
  {
    "id": "doc_456",
    "score": 0.87
  },
  {
    "id": "doc_789",
    "score": 0.82
  }
] | +| `gen_ai.retrieval.query.text` | ![Development](https://img.shields.io/badge/-development-blue) | string | The query text used for retrieval. [14] | `What is the capital of France?`; `weather in Paris` | +| `gen_ai.security.content.input.hash` | ![Development](https://img.shields.io/badge/-development-blue) | string | Hash of the input content for forensic correlation. [15] | `sha256:a3f2b8c9...` | +| `gen_ai.security.content.input.value` | ![Development](https://img.shields.io/badge/-development-blue) | any | The input content that was evaluated by the guardian. [16] | `Send an email to customer@example.com` | +| `gen_ai.security.content.modified` | ![Development](https://img.shields.io/badge/-development-blue) | boolean | Whether the content was modified by the guardrail (e.g., redacted, sanitized, rewritten). | `true`; `false` | +| `gen_ai.security.content.output.value` | ![Development](https://img.shields.io/badge/-development-blue) | any | The output content after guardian processing (if modified). [17] | `Send an email to [REDACTED]` | +| `gen_ai.security.decision.code` | ![Development](https://img.shields.io/badge/-development-blue) | int | Numeric code for the security decision (provider-specific). | `112`; `403`; `5001` | +| `gen_ai.security.decision.reason` | ![Development](https://img.shields.io/badge/-development-blue) | string | Human-readable explanation for the security decision. [18] | `PII detected in output, masked before delivery`; `Prompt injection attempt denied`; `Action exceeds agent permission scope` | +| `gen_ai.security.decision.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | The decision made by the security guardian. | `allow`; `deny`; `modify` | +| `gen_ai.security.external_event_id` | ![Development](https://img.shields.io/badge/-development-blue) | string | External correlation identifier for security events. [19] | `evt_abc123`; `incident-2024-001`; `sec-finding-xyz` | +| `gen_ai.security.policy.id` | ![Development](https://img.shields.io/badge/-development-blue) | string | Identifier of the policy that triggered the decision. | `policy_pii_v2`; `deny-topic-financial-advice`; `org-compliance-001` | +| `gen_ai.security.policy.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | Human-readable name of the triggered policy. | `PII Protection Policy`; `Financial Advice Restriction` | +| `gen_ai.security.policy.version` | ![Development](https://img.shields.io/badge/-development-blue) | string | Version of the policy that triggered the decision. | `1.0`; `2024-05-01` | +| `gen_ai.security.risk.category` | ![Development](https://img.shields.io/badge/-development-blue) | string | The category of security risk detected. [20] | `prompt_injection`; `sensitive_info_disclosure`; `jailbreak`; `custom:financial_advice_violation`; `azure:hate_speech` | +| `gen_ai.security.risk.metadata` | ![Development](https://img.shields.io/badge/-development-blue) | string[] | Non-content metadata about the detected risk. [21] | `["field:bcc", "pattern:email"]`; `["count:2", "position:output.content"]` | +| `gen_ai.security.risk.score` | ![Development](https://img.shields.io/badge/-development-blue) | double | Numeric risk/confidence score (0.0 to 1.0). | `0.85`; `0.95`; `0.42` | +| `gen_ai.security.risk.severity` | ![Development](https://img.shields.io/badge/-development-blue) | string | The severity level of the detected risk. | `low`; `medium`; `high`; `critical` | +| `gen_ai.security.target.id` | ![Development](https://img.shields.io/badge/-development-blue) | string | Identifier of the specific target the guardrail is applied to. [22] | `call_xyz789`; `tool-123`; `mem_abc456` | +| `gen_ai.security.target.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | The type of content or action the guardrail is applied to. [23] | `tool_call`; `llm_input`; `llm_output`; `tool_definition` | +| `gen_ai.system_instructions` | ![Development](https://img.shields.io/badge/-development-blue) | any | The system message or instructions provided to the GenAI model separately from the chat history. [24] | [
  {
    "type": "text",
    "content": "You are an Agent that greet users, always use greetings tool to respond"
  }
]; [
  {
    "type": "text",
    "content": "You are a language translator."
  },
  {
    "type": "text",
    "content": "Your mission is to translate text in English to French."
  }
] | | `gen_ai.token.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | The type of token being counted. | `input`; `output` | -| `gen_ai.tool.call.arguments` | ![Development](https://img.shields.io/badge/-development-blue) | any | Parameters passed to the tool call. [12] | {
    "location": "San Francisco?",
    "date": "2025-10-01"
} | +| `gen_ai.tool.call.arguments` | ![Development](https://img.shields.io/badge/-development-blue) | any | Parameters passed to the tool call. [25] | {
    "location": "San Francisco?",
    "date": "2025-10-01"
} | | `gen_ai.tool.call.id` | ![Development](https://img.shields.io/badge/-development-blue) | string | The tool call identifier. | `call_mszuSIzqtI65i1wAUOE8w5H4` | -| `gen_ai.tool.call.result` | ![Development](https://img.shields.io/badge/-development-blue) | any | The result returned by the tool call (if any and if execution was successful). [13] | {
  "temperature_range": {
    "high": 75,
    "low": 60
  },
  "conditions": "sunny"
} | -| `gen_ai.tool.definitions` | ![Development](https://img.shields.io/badge/-development-blue) | any | The list of source system tool definitions available to the GenAI agent or model. [14] | [
  {
    "type": "function",
    "name": "get_current_weather",
    "description": "Get the current weather in a given location",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "The city and state, e.g. San Francisco, CA"
        },
        "unit": {
          "type": "string",
          "enum": [
            "celsius",
            "fahrenheit"
          ]
        }
      },
      "required": [
        "location",
        "unit"
      ]
    }
  }
] | +| `gen_ai.tool.call.result` | ![Development](https://img.shields.io/badge/-development-blue) | any | The result returned by the tool call (if any and if execution was successful). [26] | {
  "temperature_range": {
    "high": 75,
    "low": 60
  },
  "conditions": "sunny"
} | +| `gen_ai.tool.definitions` | ![Development](https://img.shields.io/badge/-development-blue) | any | The list of source system tool definitions available to the GenAI agent or model. [27] | [
  {
    "type": "function",
    "name": "get_current_weather",
    "description": "Get the current weather in a given location",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "The city and state, e.g. San Francisco, CA"
        },
        "unit": {
          "type": "string",
          "enum": [
            "celsius",
            "fahrenheit"
          ]
        }
      },
      "required": [
        "location",
        "unit"
      ]
    }
  }
] | | `gen_ai.tool.description` | ![Development](https://img.shields.io/badge/-development-blue) | string | The tool description. | `Multiply two numbers` | | `gen_ai.tool.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | Name of the tool utilized by the agent. | `Flights` | -| `gen_ai.tool.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | Type of the tool utilized by the agent [15] | `function`; `extension`; `datastore` | -| `gen_ai.usage.cache_creation.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of input tokens written to a provider-managed cache. [16] | `25` | -| `gen_ai.usage.cache_read.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of input tokens served from a provider-managed cache. [17] | `50` | -| `gen_ai.usage.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of tokens used in the GenAI input (prompt). [18] | `100` | +| `gen_ai.tool.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | Type of the tool utilized by the agent [28] | `function`; `extension`; `datastore` | +| `gen_ai.usage.cache_creation.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of input tokens written to a provider-managed cache. [29] | `25` | +| `gen_ai.usage.cache_read.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of input tokens served from a provider-managed cache. [30] | `50` | +| `gen_ai.usage.input_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of tokens used in the GenAI input (prompt). [31] | `100` | | `gen_ai.usage.output_tokens` | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of tokens used in the GenAI response (completion). | `180` | -| `gen_ai.workflow.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | Human-readable name of the GenAI workflow provided by the application. [19] | `multi_agent_rag`; `customer_support_pipeline` | +| `gen_ai.workflow.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | Human-readable name of the GenAI workflow provided by the application. [32] | `multi_agent_rag`; `customer_support_pipeline` | **[1] `gen_ai.data_source.id`:** Data sources are used by AI agents and RAG applications to store grounding data. A data source may be an external database, object store, document collection, website, or any other storage system used by the GenAI agent or application. The `gen_ai.data_source.id` SHOULD match the identifier used by the GenAI system rather than a name specific to the external storage, such as a database or object store. Semantic conventions referencing `gen_ai.data_source.id` MAY also leverage additional attributes, such as `db.*`, to further identify and describe the data source. **[2] `gen_ai.evaluation.score.label`:** This attribute provides a human-readable interpretation of the evaluation score produced by an evaluator. For example, a score value of 1 could mean "relevant" in one evaluation system and "not relevant" in another, depending on the scoring range and evaluator. The label SHOULD have low cardinality. Possible values depend on the evaluation metric and evaluator used; implementations SHOULD document the possible values. -**[3] `gen_ai.input.messages`:** Instrumentations MUST follow [Input messages JSON schema](/docs/gen-ai/gen-ai-input-messages.json). +**[3] `gen_ai.guardian.id`:** This identifies the service, component, or library performing the security +evaluation - NOT the policy or configuration being applied. + +For provider-specific guardrail/policy configuration identifiers (e.g., +AWS Bedrock guardrail ARN, Azure Content Safety blocklist ID), use +`gen_ai.security.policy.id` instead. + +Example mapping: + +- Guardian: The evaluation service (e.g., "bedrock_guardrail_service", "azure_content_safety") +- Policy: The specific configuration (e.g., "arn:aws:bedrock:us-east-1:123456789:guardrail/abc123") + +**[4] `gen_ai.guardian.name`:** This identifies the security evaluation service or component, not the policy name. For policy names, use `gen_ai.security.policy.name`. + +**[5] `gen_ai.guardian.provider.name`:** This identifies the guardrail provider, which may differ from the inference provider (`gen_ai.provider.name`). For example, an agent may use OpenAI for inference and Azure AI Content Safety for content filtering in the same trace. + +**[6] `gen_ai.guardian.version`:** This is the version of the evaluating service/component, not the policy version. For policy versions, use `gen_ai.security.policy.version`. + +**[7] `gen_ai.input.messages`:** Instrumentations MUST follow [Input messages JSON schema](/docs/gen-ai/gen-ai-input-messages.json). When the attribute is recorded on events, it MUST be recorded in structured form. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise. @@ -82,9 +121,9 @@ input messages. See [Recording content on attributes](/docs/gen-ai/gen-ai-spans.md#recording-content-on-attributes) section for more details. -**[4] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. +**[8] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. -**[5] `gen_ai.output.messages`:** Instrumentations MUST follow [Output messages JSON schema](/docs/gen-ai/gen-ai-output-messages.json) +**[9] `gen_ai.output.messages`:** Instrumentations MUST follow [Output messages JSON schema](/docs/gen-ai/gen-ai-output-messages.json) Each message represents a single output choice/candidate generated by the model. Each message corresponds to exactly one generation @@ -104,11 +143,11 @@ output messages. See [Recording content on attributes](/docs/gen-ai/gen-ai-spans.md#recording-content-on-attributes) section for more details. -**[6] `gen_ai.output.type`:** This attribute SHOULD be used when the client requests output of a specific type. The model may return zero or more outputs of this type. +**[10] `gen_ai.output.type`:** This attribute SHOULD be used when the client requests output of a specific type. The model may return zero or more outputs of this type. This attribute specifies the output modality and not the actual output format. For example, if an image is requested, the actual output could be a URL pointing to an image file. Additional output format details may be recorded in the future in the `gen_ai.output.{type}.*` attributes. -**[7] `gen_ai.provider.name`:** The attribute SHOULD be set based on the instrumentation's best +**[11] `gen_ai.provider.name`:** The attribute SHOULD be set based on the instrumentation's best knowledge and may differ from the actual model provider. Multiple providers, including Azure OpenAI, Gemini, and AI hosting platforms @@ -127,9 +166,9 @@ should have the `gen_ai.provider.name` set to `aws.bedrock` and include applicable `aws.bedrock.*` attributes and are not expected to include `openai.*` attributes. -**[8] `gen_ai.request.encoding_formats`:** In some GenAI systems the encoding formats are called embedding types. Also, some GenAI systems only accept a single format per request. +**[12] `gen_ai.request.encoding_formats`:** In some GenAI systems the encoding formats are called embedding types. Also, some GenAI systems only accept a single format per request. -**[9] `gen_ai.retrieval.documents`:** Instrumentations MUST follow [Retrieval documents JSON schema](/docs/gen-ai/gen-ai-retrieval-documents.json). +**[13] `gen_ai.retrieval.documents`:** Instrumentations MUST follow [Retrieval documents JSON schema](/docs/gen-ai/gen-ai-retrieval-documents.json). When the attribute is recorded on events, it MUST be recorded in structured form. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise. @@ -137,12 +176,94 @@ format is not supported and SHOULD be recorded in structured form otherwise. Each document object SHOULD contain at least the following properties: `id` (string): A unique identifier for the document, `score` (double): The relevance score of the document -**[10] `gen_ai.retrieval.query.text`:** +**[14] `gen_ai.retrieval.query.text`:** > [!Warning] > This attribute may contain sensitive information. -**[11] `gen_ai.system_instructions`:** This attribute SHOULD be used when the corresponding provider or API +**[15] `gen_ai.security.content.input.hash`:** Use when full content capture is not desired but correlation is needed. Instrumentations SHOULD document the algorithm and any salting/HMAC approach used. + +**[16] `gen_ai.security.content.input.value`:** + +> [!WARNING] +> This attribute may contain sensitive information including user/PII +> data. Instrumentations SHOULD NOT capture this by default. Enable via +> opt-in configuration only. + +This attribute MAY be truncated. For correlation without full content, +consider `gen_ai.security.content.input.hash`. + +**[17] `gen_ai.security.content.output.value`:** + +> [!WARNING] +> This attribute may contain sensitive information. Instrumentations +> SHOULD NOT capture this by default. Enable via opt-in configuration +> only. + +For `modify` decisions, this MAY contain the sanitized/redacted result. + +**[18] `gen_ai.security.decision.reason`:** The value SHOULD be low-cardinality and MUST NOT contain sensitive user content or other high-risk data. + +**[19] `gen_ai.security.external_event_id`:** This attribute links the telemetry to an external security event record +in systems such as SIEM, incident management, or security dashboards. + +The value typically comes from the response of an external security +inspection service or may be included in response headers when inspection +happens alongside the LLM call. + +Use this when correlation with external security systems is required +beyond what `gen_ai.security.policy.id` provides. + +**[20] `gen_ai.security.risk.category`:** This attribute is free-form to accommodate provider-specific, +organization-specific, or emerging risk categories. + +Suggested values aligned with OWASP LLM Top 10 2025 include: + +- `prompt_injection` (LLM01) +- `sensitive_info_disclosure` (LLM02) +- `supply_chain` (LLM03) +- `data_and_model_poisoning` (LLM04) +- `improper_output_handling` (LLM05) +- `excessive_agency` (LLM06) +- `system_prompt_leakage` (LLM07) +- `vector_and_embedding_weaknesses` (LLM08) +- `misinformation` (LLM09) +- `unbounded_consumption` (LLM10) + +Instrumentations MAY use additional values when appropriate, for +example: `jailbreak`, `toxicity`, `pii`, `custom:*`, `azure:*`. + +**[21] `gen_ai.security.risk.metadata`:** + +> [!WARNING] +> This attribute MUST NOT contain sensitive user content, PII, or other +> high-risk data. + +Example values include: + +- Field identifiers: `field:bcc`, `parameter:query` +- Pattern types: `pattern:ssn`, `pattern:credit_card` +- Counts: `count:3` +- Positions: `position:input[0].content` + +**[22] `gen_ai.security.target.id`:** For example, a tool call identifier, request identifier, or memory entry identifier, if applicable. + +**[23] `gen_ai.security.target.type`:** This attribute is free-form to accommodate provider-specific, +organization-specific, or emerging target types. + +Suggested values include: + +- `llm_input`: Prompt or messages being sent to the model. +- `llm_output`: Response or messages returned from the model. +- `tool_call`: Tool execution request (tool call invocation). +- `tool_definition`: Tool definition or schema (tool declaration). +- `memory_store`: Data being written to memory. +- `memory_retrieve`: Data being read from memory. +- `knowledge_query`: Knowledge/RAG query being sent. +- `knowledge_result`: Knowledge/RAG results being returned. +- `message`: Conversation message (user, assistant, tool). + +**[24] `gen_ai.system_instructions`:** This attribute SHOULD be used when the corresponding provider or API allows to provide system instructions or messages separately from the chat history. @@ -163,7 +284,7 @@ system instructions. See [Recording content on attributes](/docs/gen-ai/gen-ai-spans.md#recording-content-on-attributes) section for more details. -**[12] `gen_ai.tool.call.arguments`:** +**[25] `gen_ai.tool.call.arguments`:** > [!WARNING] > This attribute may contain sensitive information. @@ -172,7 +293,7 @@ It's expected to be an object - in case a serialized string is available to the instrumentation, the instrumentation SHOULD do the best effort to deserialize it to an object. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise. -**[13] `gen_ai.tool.call.result`:** +**[26] `gen_ai.tool.call.result`:** > [!WARNING] > This attribute may contain sensitive information. @@ -181,7 +302,7 @@ It's expected to be an object - in case a serialized string is available to the instrumentation, the instrumentation SHOULD do the best effort to deserialize it to an object. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise. -**[14] `gen_ai.tool.definitions`:** The value of this attribute matches source system tool definition format. +**[27] `gen_ai.tool.definitions`:** The value of this attribute matches source system tool definition format. It's expected to be an array of objects where each object represents a tool definition. In case a serialized string is available to the instrumentation, the instrumentation SHOULD do the best effort to @@ -191,22 +312,32 @@ Since this attribute could be large, it's NOT RECOMMENDED to populate it by default. Instrumentations MAY provide a way to enable populating this attribute. -**[15] `gen_ai.tool.type`:** Extension: A tool executed on the agent-side to directly call external APIs, bridging the gap between the agent and real-world systems. +**[28] `gen_ai.tool.type`:** Extension: A tool executed on the agent-side to directly call external APIs, bridging the gap between the agent and real-world systems. Agent-side operations involve actions that are performed by the agent on the server or within the agent's controlled environment. Function: A tool executed on the client-side, where the agent generates parameters for a predefined function, and the client executes the logic. Client-side operations are actions taken on the user's end or within the client application. Datastore: A tool used by the agent to access and query structured or unstructured external data for retrieval-augmented tasks or knowledge updates. -**[16] `gen_ai.usage.cache_creation.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. +**[29] `gen_ai.usage.cache_creation.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. -**[17] `gen_ai.usage.cache_read.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. +**[30] `gen_ai.usage.cache_read.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. -**[18] `gen_ai.usage.input_tokens`:** This value SHOULD include all types of input tokens, including cached tokens. +**[31] `gen_ai.usage.input_tokens`:** This value SHOULD include all types of input tokens, including cached tokens. Instrumentations SHOULD make a best effort to populate this value, using a total provided by the provider when available or, depending on the provider API, by summing different token types parsed from the provider output. -**[19] `gen_ai.workflow.name`:** This attribute can be populated in different frameworks eg: name of the first chain in LangChain OR name of the crew in CrewAI. +**[32] `gen_ai.workflow.name`:** This attribute can be populated in different frameworks eg: name of the first chain in LangChain OR name of the crew in CrewAI. + +--- + +`gen_ai.guardian.provider.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --- | --- | --- | +| `aws.bedrock` | [AWS Bedrock Guardrails](https://aws.amazon.com/bedrock/guardrails/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `azure.ai.content_safety` | [Azure AI Content Safety](https://azure.microsoft.com/products/ai-services/ai-content-safety/) | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.model_armor` | [GCP Model Armor](https://cloud.google.com/security/products/model-armor) | ![Development](https://img.shields.io/badge/-development-blue) | --- @@ -214,6 +345,7 @@ by summing different token types parsed from the provider output. | Value | Description | Stability | | --- | --- | --- | +| `apply_guardrail` | Apply a security guardrail to content or an action | ![Development](https://img.shields.io/badge/-development-blue) | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | | `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -247,9 +379,9 @@ by summing different token types parsed from the provider output. | `azure.ai.openai` | [Azure OpenAI](https://azure.microsoft.com/products/ai-services/openai-service/) | ![Development](https://img.shields.io/badge/-development-blue) | | `cohere` | [Cohere](https://cohere.com/) | ![Development](https://img.shields.io/badge/-development-blue) | | `deepseek` | [DeepSeek](https://www.deepseek.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gemini` | [Gemini](https://cloud.google.com/products/gemini) [20] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gen_ai` | Any Google generative AI endpoint [21] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [22] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gemini` | [Gemini](https://cloud.google.com/products/gemini) [33] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai` | Any Google generative AI endpoint [34] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [35] | ![Development](https://img.shields.io/badge/-development-blue) | | `groq` | [Groq](https://groq.com/) | ![Development](https://img.shields.io/badge/-development-blue) | | `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) | ![Development](https://img.shields.io/badge/-development-blue) | | `mistral_ai` | [Mistral AI](https://mistral.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | @@ -257,11 +389,35 @@ by summing different token types parsed from the provider output. | `perplexity` | [Perplexity](https://www.perplexity.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | | `x_ai` | [xAI](https://x.ai/) | ![Development](https://img.shields.io/badge/-development-blue) | -**[20]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. +**[33]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. -**[21]:** May be used when specific backend is unknown. +**[34]:** May be used when specific backend is unknown. -**[22]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. +**[35]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. + +--- + +`gen_ai.security.decision.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --- | --- | --- | +| `allow` | Request permitted to proceed without modification. | ![Development](https://img.shields.io/badge/-development-blue) | +| `audit` | Request logged for audit purposes only, no enforcement. | ![Development](https://img.shields.io/badge/-development-blue) | +| `deny` | Request denied and operation halted. | ![Development](https://img.shields.io/badge/-development-blue) | +| `modify` | Request permitted with modifications (redaction, sanitization). | ![Development](https://img.shields.io/badge/-development-blue) | +| `warn` | Request permitted but flagged for review. | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`gen_ai.security.risk.severity` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| --- | --- | --- | +| `critical` | Critical severity risk requiring immediate action. | ![Development](https://img.shields.io/badge/-development-blue) | +| `high` | High severity risk. | ![Development](https://img.shields.io/badge/-development-blue) | +| `low` | Low severity risk. | ![Development](https://img.shields.io/badge/-development-blue) | +| `medium` | Medium severity risk. | ![Development](https://img.shields.io/badge/-development-blue) | +| `none` | No risk detected. | ![Development](https://img.shields.io/badge/-development-blue) | --- @@ -298,9 +454,9 @@ Describes deprecated `gen_ai` attributes. | `azure.ai.openai` | Azure OpenAI | ![Development](https://img.shields.io/badge/-development-blue) | | `cohere` | Cohere | ![Development](https://img.shields.io/badge/-development-blue) | | `deepseek` | DeepSeek | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gemini` | Gemini [23] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.gen_ai` | Any Google generative AI endpoint [24] | ![Development](https://img.shields.io/badge/-development-blue) | -| `gcp.vertex_ai` | Vertex AI [25] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gemini` | Gemini [36] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai` | Any Google generative AI endpoint [37] | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.vertex_ai` | Vertex AI [38] | ![Development](https://img.shields.io/badge/-development-blue) | | `groq` | Groq | ![Development](https://img.shields.io/badge/-development-blue) | | `ibm.watsonx.ai` | IBM Watsonx AI | ![Development](https://img.shields.io/badge/-development-blue) | | `mistral_ai` | Mistral AI | ![Development](https://img.shields.io/badge/-development-blue) | @@ -308,11 +464,11 @@ Describes deprecated `gen_ai` attributes. | `perplexity` | Perplexity | ![Development](https://img.shields.io/badge/-development-blue) | | `xai` | xAI | ![Development](https://img.shields.io/badge/-development-blue) | -**[23]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'. +**[36]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'. -**[24]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'. +**[37]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'. -**[25]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'. +**[38]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'. ## Deprecated OpenAI GenAI Attributes diff --git a/model/gen-ai/events.yaml b/model/gen-ai/events.yaml index ce86109a6d..d70e3a787d 100644 --- a/model/gen-ai/events.yaml +++ b/model/gen-ai/events.yaml @@ -45,6 +45,33 @@ groups: the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. + - id: event.gen_ai.security.finding + name: gen_ai.security.finding + type: event + stability: development + brief: > + Reports a specific security finding detected during guardian evaluation. + note: | + Multiple findings MAY be emitted for a single guardian span. + + Events SHOULD be parented to the `span.gen_ai.apply_guardrail.internal` span when possible. + attributes: + - ref: gen_ai.security.risk.category + requirement_level: required + - ref: gen_ai.security.risk.severity + requirement_level: required + - ref: gen_ai.security.risk.score + requirement_level: recommended + - ref: gen_ai.security.risk.metadata + requirement_level: recommended + - ref: gen_ai.security.policy.id + requirement_level: + conditionally_required: if triggered by a specific policy + - ref: gen_ai.security.policy.name + requirement_level: recommended + - ref: gen_ai.security.policy.version + requirement_level: recommended + - id: event.gen_ai.client.operation.exception name: gen_ai.client.operation.exception stability: development diff --git a/model/gen-ai/registry.yaml b/model/gen-ai/registry.yaml index ddd2408b27..00538bc6b8 100644 --- a/model/gen-ai/registry.yaml +++ b/model/gen-ai/registry.yaml @@ -364,6 +364,287 @@ groups: } ] + - id: gen_ai.guardian.id + stability: development + type: string + brief: The unique identifier of the security guardian (the evaluating service or component). + note: | + This identifies the service, component, or library performing the security + evaluation - NOT the policy or configuration being applied. + + For provider-specific guardrail/policy configuration identifiers (e.g., + AWS Bedrock guardrail ARN, Azure Content Safety blocklist ID), use + `gen_ai.security.policy.id` instead. + + Example mapping: + + - Guardian: The evaluation service (e.g., "bedrock_guardrail_service", "azure_content_safety") + - Policy: The specific configuration (e.g., "arn:aws:bedrock:us-east-1:123456789:guardrail/abc123") + examples: ['guard_abc123', 'content-filter-v2', 'custom-guardian-001'] + - id: gen_ai.guardian.name + stability: development + type: string + brief: Human-readable name of the guardian (the evaluating service or component). + note: > + This identifies the security evaluation service or component, not the + policy name. For policy names, use `gen_ai.security.policy.name`. + examples: ['Azure Content Safety', 'Bedrock Guardrails', 'Custom PII Filter'] + - id: gen_ai.guardian.version + stability: development + type: string + brief: Version of the guardian service or component. + note: > + This is the version of the evaluating service/component, not the policy + version. For policy versions, use `gen_ai.security.policy.version`. + examples: ['1.0.0', '2024-05-01', 'v2'] + - id: gen_ai.guardian.provider.name + stability: development + type: + members: + - id: azure.ai.content_safety + value: "azure.ai.content_safety" + brief: '[Azure AI Content Safety](https://azure.microsoft.com/products/ai-services/ai-content-safety/)' + stability: development + - id: aws.bedrock + value: "aws.bedrock" + brief: '[AWS Bedrock Guardrails](https://aws.amazon.com/bedrock/guardrails/)' + stability: development + - id: gcp.model_armor + value: "gcp.model_armor" + brief: '[GCP Model Armor](https://cloud.google.com/security/products/model-armor)' + stability: development + brief: The provider or vendor of the guardian service. + note: > + This identifies the guardrail provider, which may differ from the inference + provider (`gen_ai.provider.name`). For example, an agent may use OpenAI for + inference and Azure AI Content Safety for content filtering in the same trace. + examples: ['azure.ai.content_safety', 'aws.bedrock', 'gcp.model_armor'] + + - id: gen_ai.security.decision.type + stability: development + type: + members: + - id: allow + value: "allow" + brief: Request permitted to proceed without modification. + stability: development + - id: deny + value: "deny" + brief: Request denied and operation halted. + stability: development + - id: modify + value: "modify" + brief: Request permitted with modifications (redaction, sanitization). + stability: development + - id: warn + value: "warn" + brief: Request permitted but flagged for review. + stability: development + - id: audit + value: "audit" + brief: Request logged for audit purposes only, no enforcement. + stability: development + brief: The decision made by the security guardian. + examples: ['allow', 'deny', 'modify'] + - id: gen_ai.security.decision.reason + stability: development + type: string + brief: Human-readable explanation for the security decision. + note: > + The value SHOULD be low-cardinality and MUST NOT contain sensitive user + content or other high-risk data. + examples: + - 'PII detected in output, masked before delivery' + - 'Prompt injection attempt denied' + - 'Action exceeds agent permission scope' + - id: gen_ai.security.decision.code + stability: development + type: int + brief: Numeric code for the security decision (provider-specific). + examples: [112, 403, 5001] + + - id: gen_ai.security.target.type + stability: development + type: string + brief: The type of content or action the guardrail is applied to. + note: | + This attribute is free-form to accommodate provider-specific, + organization-specific, or emerging target types. + + Suggested values include: + + - `llm_input`: Prompt or messages being sent to the model. + - `llm_output`: Response or messages returned from the model. + - `tool_call`: Tool execution request (tool call invocation). + - `tool_definition`: Tool definition or schema (tool declaration). + - `memory_store`: Data being written to memory. + - `memory_retrieve`: Data being read from memory. + - `knowledge_query`: Knowledge/RAG query being sent. + - `knowledge_result`: Knowledge/RAG results being returned. + - `message`: Conversation message (user, assistant, tool). + examples: ['tool_call', 'llm_input', 'llm_output', 'tool_definition'] + - id: gen_ai.security.target.id + stability: development + type: string + brief: Identifier of the specific target the guardrail is applied to. + note: > + For example, a tool call identifier, request identifier, or memory + entry identifier, if applicable. + examples: ['call_xyz789', 'tool-123', 'mem_abc456'] + + - id: gen_ai.security.risk.category + stability: development + type: string + brief: The category of security risk detected. + note: | + This attribute is free-form to accommodate provider-specific, + organization-specific, or emerging risk categories. + + Suggested values aligned with OWASP LLM Top 10 2025 include: + + - `prompt_injection` (LLM01) + - `sensitive_info_disclosure` (LLM02) + - `supply_chain` (LLM03) + - `data_and_model_poisoning` (LLM04) + - `improper_output_handling` (LLM05) + - `excessive_agency` (LLM06) + - `system_prompt_leakage` (LLM07) + - `vector_and_embedding_weaknesses` (LLM08) + - `misinformation` (LLM09) + - `unbounded_consumption` (LLM10) + + Instrumentations MAY use additional values when appropriate, for + example: `jailbreak`, `toxicity`, `pii`, `custom:*`, `azure:*`. + examples: + - 'prompt_injection' + - 'sensitive_info_disclosure' + - 'jailbreak' + - 'custom:financial_advice_violation' + - 'azure:hate_speech' + - id: gen_ai.security.risk.severity + stability: development + type: + members: + - id: none + value: "none" + brief: No risk detected. + stability: development + - id: low + value: "low" + brief: Low severity risk. + stability: development + - id: medium + value: "medium" + brief: Medium severity risk. + stability: development + - id: high + value: "high" + brief: High severity risk. + stability: development + - id: critical + value: "critical" + brief: Critical severity risk requiring immediate action. + stability: development + brief: The severity level of the detected risk. + examples: ['low', 'medium', 'high', 'critical'] + - id: gen_ai.security.risk.score + stability: development + type: double + brief: Numeric risk/confidence score (0.0 to 1.0). + examples: [0.85, 0.95, 0.42] + - id: gen_ai.security.risk.metadata + stability: development + type: string[] + brief: Non-content metadata about the detected risk. + note: | + > [!WARNING] + > This attribute MUST NOT contain sensitive user content, PII, or other + > high-risk data. + + Example values include: + + - Field identifiers: `field:bcc`, `parameter:query` + - Pattern types: `pattern:ssn`, `pattern:credit_card` + - Counts: `count:3` + - Positions: `position:input[0].content` + examples: + - ['field:bcc', 'pattern:email'] + - ['count:2', 'position:output.content'] + + - id: gen_ai.security.policy.id + stability: development + type: string + brief: Identifier of the policy that triggered the decision. + examples: ['policy_pii_v2', 'deny-topic-financial-advice', 'org-compliance-001'] + - id: gen_ai.security.policy.name + stability: development + type: string + brief: Human-readable name of the triggered policy. + examples: ['PII Protection Policy', 'Financial Advice Restriction'] + - id: gen_ai.security.policy.version + stability: development + type: string + brief: Version of the policy that triggered the decision. + examples: ['1.0', '2024-05-01'] + + - id: gen_ai.security.content.input.value + stability: development + type: any + brief: The input content that was evaluated by the guardian. + note: | + > [!WARNING] + > This attribute may contain sensitive information including user/PII + > data. Instrumentations SHOULD NOT capture this by default. Enable via + > opt-in configuration only. + + This attribute MAY be truncated. For correlation without full content, + consider `gen_ai.security.content.input.hash`. + examples: + - 'Send an email to customer@example.com' + - id: gen_ai.security.content.output.value + stability: development + type: any + brief: The output content after guardian processing (if modified). + note: | + > [!WARNING] + > This attribute may contain sensitive information. Instrumentations + > SHOULD NOT capture this by default. Enable via opt-in configuration + > only. + + For `modify` decisions, this MAY contain the sanitized/redacted result. + examples: + - 'Send an email to [REDACTED]' + - id: gen_ai.security.content.input.hash + stability: development + type: string + brief: Hash of the input content for forensic correlation. + note: > + Use when full content capture is not desired but correlation is needed. + Instrumentations SHOULD document the algorithm and any salting/HMAC + approach used. + examples: ['sha256:a3f2b8c9...'] + - id: gen_ai.security.content.modified + stability: development + type: boolean + brief: Whether the content was modified by the guardrail (e.g., redacted, sanitized, rewritten). + examples: [true, false] + + - id: gen_ai.security.external_event_id + stability: development + type: string + brief: External correlation identifier for security events. + note: | + This attribute links the telemetry to an external security event record + in systems such as SIEM, incident management, or security dashboards. + + The value typically comes from the response of an external security + inspection service or may be included in response headers when inspection + happens alongside the LLM call. + + Use this when correlation with external security systems is required + beyond what `gen_ai.security.policy.id` provides. + examples: ['evt_abc123', 'incident-2024-001', 'sec-finding-xyz'] + - id: gen_ai.data_source.id stability: development type: string @@ -410,6 +691,10 @@ groups: value: "execute_tool" brief: 'Execute a tool' stability: development + - id: apply_guardrail + value: "apply_guardrail" + brief: 'Apply a security guardrail to content or an action' + stability: development - id: invoke_workflow value: "invoke_workflow" brief: 'Invoke GenAI workflow' diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml index 2ff5f5c639..8bce8ccab4 100644 --- a/model/gen-ai/spans.yaml +++ b/model/gen-ai/spans.yaml @@ -440,6 +440,79 @@ groups: the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. + - id: span.gen_ai.apply_guardrail.internal + type: span + stability: development + span_kind: internal + brief: Describes a security guardian evaluation. + note: | + `gen_ai.operation.name` SHOULD be `apply_guardrail`. + + **Span name** SHOULD be `apply_guardrail {gen_ai.guardian.name} {gen_ai.security.target.type}`. + When `gen_ai.guardian.name` is not available, it SHOULD be `apply_guardrail {gen_ai.security.target.type}`. + + Guardian spans SHOULD be children of the operation span they are protecting (for example, + `span.gen_ai.inference.client` or `span.gen_ai.execute_tool.internal`). + + Multiple guardian spans MAY exist under a single operation span if multiple guardians are chained. + attributes: + - ref: gen_ai.operation.name + requirement_level: required + - ref: gen_ai.guardian.id + requirement_level: + conditionally_required: if available + - ref: gen_ai.guardian.name + requirement_level: recommended + - ref: gen_ai.guardian.version + requirement_level: recommended + - ref: gen_ai.guardian.provider.name + requirement_level: recommended + - ref: gen_ai.security.decision.type + requirement_level: required + - ref: gen_ai.security.decision.reason + requirement_level: + conditionally_required: if `gen_ai.security.decision.type` is not `allow` and a reason is available + - ref: gen_ai.security.decision.code + requirement_level: recommended + - ref: gen_ai.security.target.type + requirement_level: required + - ref: gen_ai.security.target.id + requirement_level: + conditionally_required: if available + - ref: gen_ai.security.policy.id + requirement_level: + conditionally_required: if a policy triggered the decision + - ref: gen_ai.security.policy.name + requirement_level: recommended + - ref: gen_ai.security.policy.version + requirement_level: recommended + - ref: gen_ai.security.external_event_id + requirement_level: + conditionally_required: if correlation with external security systems is needed + - ref: gen_ai.security.content.input.value + requirement_level: opt_in + - ref: gen_ai.security.content.output.value + requirement_level: opt_in + - ref: gen_ai.security.content.input.hash + requirement_level: + conditionally_required: if correlation is needed and available + - ref: gen_ai.security.content.modified + requirement_level: + conditionally_required: if `gen_ai.security.decision.type` is `modify` + - ref: gen_ai.agent.id + requirement_level: + conditionally_required: when applicable + - ref: gen_ai.conversation.id + requirement_level: + conditionally_required: when available + - ref: error.type + requirement_level: + conditionally_required: "if the operation ended in an error" + note: | + The `error.type` SHOULD match the error code returned by the guardian or the client library, + the canonical name of exception that occurred, or another low-cardinality error identifier. + Instrumentations SHOULD document the list of errors they report. + - id: span.aws.bedrock.client extends: span.gen_ai.inference.client stability: development