Add gen_ai _ref attributes for referencing external uploaded content

.chloggen/genai-refs.yaml

@@ -0,0 +1,4 @@
+change_type: enhancement
+component: gen_ai
+note: Add gen_ai `_ref` attributes for referencing external uploaded content
+issues: [2753]

model/gen-ai/registry.yaml

@@ -471,6 +471,20 @@ groups:
                   "content": "Your mission is to translate text in English to French."
                 }
               ]
+      - id: gen_ai.system_instructions_ref
+        stability: development
+        type: string
+        brief: The link to the system message or instructions recorded in a separate
+          storage.
+        examples: ["s3://acme.prod.support_bot.chats.2025/conv_1234/invocation_42.json"]
+        note: >
+          This attribute records the reference to the content of
+          `gen_ai.system_instructions` attribute when the content is too large or
+          contains sensitive information and should be stored separately from
+          general telemetry data.
+
+          Refer to the [Uploading content to external storage](/docs/gen-ai/gen-ai-spans.md#uploading-content-to-external-storage)
+          section for more details.
       - id: gen_ai.input.messages
         stability: development
         type: any
@@ -527,6 +541,19 @@ groups:
                   ]
                 }
               ]
+      - id: gen_ai.input.messages_ref
+        stability: development
+        type: string
+        brief: The link to the input messages recorded in a separate storage.
+        examples: ["s3://acme.prod.support_bot.chats.2025/conv_1234/run_42.json"]
+        note: |
+          This attribute records the reference to the content of
+          `gen_ai.input.messages` attribute when the content is too large or
+          contains sensitive information and should be stored separately from
+          general telemetry data.
+
+          Refer to the [Uploading content to external storage](/docs/gen-ai/gen-ai-spans.md#uploading-content-to-external-storage)
+          section for more details.
       - id: gen_ai.output.messages
         stability: development
         type: any
@@ -566,6 +593,19 @@ groups:
                   "finish_reason": "stop"
                 }
               ]
+      - id: gen_ai.output.messages_ref
+        stability: development
+        type: string
+        brief: The link to the model or agent output recorded in a separate storage.
+        examples: ["s3://acme.prod.support_bot.chats.2025/conv_1234/run_42.json"]
+        note: |
+          This attribute records the reference to the content of
+          `gen_ai.output.messages` attribute when the content is too large or
+          contains sensitive information and should be stored separately from
+          general telemetry data.
+
+          Refer to the [Uploading content to external storage](/docs/gen-ai/gen-ai-spans.md#uploading-content-to-external-storage)
+          section for more details.
       - id: gen_ai.evaluation.name
         stability: development
         type: string

model/gen-ai/spans.yaml

@@ -91,10 +91,19 @@ groups:
 
       - ref: gen_ai.system_instructions
         requirement_level: opt_in
+      - ref: gen_ai.system_instructions_ref
+        requirement_level:
+          recommended: if applicable
       - ref: gen_ai.input.messages
         requirement_level: opt_in
+      - ref: gen_ai.input.messages_ref
+        requirement_level:
+          recommended: if applicable
       - ref: gen_ai.output.messages
         requirement_level: opt_in
+      - ref: gen_ai.output.messages_ref
+        requirement_level:
+          recommended: if applicable
       - ref: gen_ai.tool.definitions
         requirement_level: opt_in
 
@@ -282,7 +291,6 @@ groups:
       - ref: gen_ai.output.messages
         requirement_level: opt_in
 
-
   - id: span.gen_ai.execute_tool.internal
     type: span
     stability: development