Merge branch 'main' into ignore-sporadic-failing-link

.chloggen/1469.yaml

@@ -0,0 +1,5 @@
+change_type: 'enhancement'
+component: gen_ai
+note: Yamlify gen_ai events and clean up examples.
+
+issues: [1469]

.chloggen/clarify-temporary-destination.yaml

@@ -0,0 +1,5 @@
+change_type: enhancement
+component: messaging
+note: Further clarify `{destination}` value on span names
+issues: [1635]
+subtext:

docs/messaging/messaging-spans.md

@@ -191,19 +191,24 @@ Messaging spans SHOULD follow the overall [guidelines for span names](https://gi
 
 <!-- markdown-link-check-disable -->
 <!-- HTML anchors are not supported https://github.com/tcort/markdown-link-check/issues/225-->
-The **span name** SHOULD be `{messaging.operation.name} {destination}` (see below for the exact definition of the [`{destination}`](#destination-placeholder) placeholder).
+The **span name** SHOULD be `{messaging.operation.name} {destination}`
+(see below for the exact definition of the [`{destination}`](#destination-placeholder) placeholder).
 <!-- markdown-link-check-enable -->
 
-Semantic conventions for individual messaging systems MAY specify different span name format and then MUST document it in semantic conventions for specific messaging technologies.
+Semantic conventions for individual messaging systems MAY specify different
+span name format and then MUST document it in semantic conventions
+for specific messaging technologies.
 
-The <span id="destination-placeholder">`{destination}`</span> SHOULD describe the entity that the operation is performed against
+The <span id="destination-placeholder">`{destination}`</span>
+SHOULD describe the entity that the operation is performed against
 and SHOULD adhere to one of the following values, provided they are accessible:
 
 1. `messaging.destination.template` SHOULD be used when it is available.
 2. `messaging.destination.name` SHOULD be used when the destination is known to be neither [temporary nor anonymous](#temporary-and-anonymous-destinations).
 3. `server.address:server.port` SHOULD be used only for operations not targeting any specific destination(s).
 
-If a corresponding `{destination}` value is not available for a specific operation, the instrumentation SHOULD omit the `{destination}`.
+If a (low-cardinality) corresponding `{destination}` value is not available for
+a specific operation, the instrumentation SHOULD omit the `{destination}`.
 
 Examples:
 

model/gen-ai/events.yaml

@@ -12,32 +12,172 @@ groups:
     type: event
     stability: experimental
     brief: >
-      This event describes the instructions passed to the GenAI system inside the prompt.
+      This event describes the system instructions passed to the GenAI model.
     extends: gen_ai.common.event.attributes
+    body:
+      id: gen_ai.system.message
+      requirement_level: opt_in
+      type: map
+      fields:
+        - id: content
+          type: undefined
+          stability: experimental
+          brief: >
+            The contents of the system message.
+          examples: ["You're a helpful bot"]
+          requirement_level: opt_in
+        - id: role
+          type: string
+          stability: experimental
+          brief: >
+            The actual role of the message author as passed in the message.
+          examples: ["system", "instruction"]
+          requirement_level:
+            conditionally_required: if available and not equal to `system`.
 
   - id: event.gen_ai.user.message
     name: gen_ai.user.message
     type: event
     stability: experimental
     brief: >
-      This event describes the prompt message specified by the user.
+      This event describes the user message passed to the GenAI model.
     extends: gen_ai.common.event.attributes
+    body:
+      id: gen_ai.user.message
+      requirement_level: opt_in
+      type: map
+      fields:
+        - id: content
+          type: undefined
+          stability: experimental
+          brief: >
+            The contents of the user message.
+          examples: ["What's the weather in Paris?"]
+          requirement_level: opt_in
+        - id: role
+          type: string
+          stability: experimental
+          brief: >
+            The actual role of the message author as passed in the message.
+          examples: ["user", "customer"]
+          requirement_level:
+            conditionally_required: if available and not equal to `user`.
 
   - id: event.gen_ai.assistant.message
     name: gen_ai.assistant.message
     type: event
     stability: experimental
     brief: >
-      This event describes the assistant message passed to GenAI system or received from it.
+      This event describes the assistant message passed to GenAI system.
     extends: gen_ai.common.event.attributes
+    body:
+      id: gen_ai.assistant.message
+      requirement_level: opt_in
+      type: map
+      fields:
+        - id: content
+          type: undefined
+          stability: experimental
+          brief: >
+            The contents of the tool message.
+          examples: ["The weather in Paris is rainy and overcast, with temperatures around 57°F"]
+          requirement_level: opt_in
+        - id: role
+          type: string
+          stability: experimental
+          brief: >
+            The actual role of the message author as passed in the message.
+          examples: ["assistant", "bot"]
+          requirement_level:
+            conditionally_required: if available and not equal to `assistant`.
+        - id: tool_calls
+          type: map[]
+          stability: experimental
+          brief: >
+            The tool calls generated by the model, such as function calls.
+          requirement_level:
+            conditionally_required: if available
+          fields:
+            - id: id
+              type: string
+              stability: experimental
+              brief: >
+                The id of the tool call.
+              examples: ["call_mszuSIzqtI65i1wAUOE8w5H4"]
+              requirement_level: required
+            - id: type
+              type: enum
+              members:
+                - id: function
+                  value: 'function'
+                  brief: Function
+              stability: experimental
+              brief: >
+                The type of the tool.
+              examples: ["function"]
+              requirement_level: required
+            - id: function
+              type: map
+              stability: experimental
+              brief: >
+                The function call.
+              requirement_level: required
+              fields:
+                - id: name
+                  type: string
+                  stability: experimental
+                  brief: >
+                    The name of the function.
+                  examples: ["get_weather"]
+                  requirement_level: required
+                - id: arguments
+                  type: undefined
+                  stability: experimental
+                  brief: >
+                    The arguments of the function as provided in the LLM response.
+                  note: >
+                    Models usually return arguments as a JSON string. In this case, it's
+                    RECOMMENDED to provide arguments as is without attempting to deserialize them.
+
+                    Semantic conventions for individual systems MAY specify a different type for
+                    arguments field.
+                  examples: ['{\"location\": \"Paris\"}']
+                  requirement_level: opt_in
 
   - id: event.gen_ai.tool.message
     name: gen_ai.tool.message
     type: event
     stability: experimental
     brief: >
-      This event describes the tool or function response message.
+      This event describes the response from a tool or function call passed to the GenAI model.
     extends: gen_ai.common.event.attributes
+    body:
+      id: gen_ai.tool.message
+      requirement_level: opt_in
+      type: map
+      fields:
+        - id: content
+          type: undefined
+          stability: experimental
+          brief: >
+            The contents of the tool message.
+          examples: ["rainy, 57°F"]
+          requirement_level: opt_in
+        - id: role
+          type: string
+          stability: experimental
+          brief: >
+            The actual role of the message author as passed in the message.
+          examples: ["tool", "function"]
+          requirement_level:
+            conditionally_required: if available and not equal to `tool`.
+        - id: id
+          type: string
+          stability: experimental
+          brief: >
+            Tool call id that this message is responding to.
+          examples: ["call_mszuSIzqtI65i1wAUOE8w5H4"]
+          requirement_level: required
 
   - id: event.gen_ai.choice
     name: gen_ai.choice
@@ -46,3 +186,123 @@ groups:
     brief: >
       This event describes the Gen AI response message.
     extends: gen_ai.common.event.attributes
+    body:
+      id: gen_ai.choice
+      requirement_level: opt_in
+      type: map
+      note: >
+        If GenAI model returns multiple choices, each choice SHOULD be recorded as an individual event.
+        When response is streamed, instrumentations that report response events MUST reconstruct and report
+        the full message and MUST NOT report individual chunks as events.
+        If the request to GenAI model fails with an error before content is received,
+        instrumentation SHOULD report an event with truncated content (if enabled).
+        If `finish_reason` was not received, it MUST be set to `error`.
+      fields:
+        - id: index
+          type: int
+          stability: experimental
+          brief: >
+            The index of the choice in the list of choices.
+          examples: [0, 1]
+          requirement_level: required
+        - id: finish_reason
+          type: enum
+          members:
+            - id: stop
+              value: 'stop'
+              stability: experimental
+              brief: Stop
+            - id: tool_calls
+              value: 'tool_calls'
+              stability: experimental
+              brief: Tool Calls
+            - id: content_filter
+              value: 'content_filter'
+              stability: experimental
+              brief: Content Filter
+            - id: length
+              value: 'length'
+              stability: experimental
+              brief: Length
+            - id: error
+              value: 'error'
+              stability: experimental
+              brief: Error
+          stability: experimental
+          brief: >
+            The reason the model stopped generating tokens.
+          requirement_level: required
+        - id: message
+          type: map
+          stability: experimental
+          brief: >
+            GenAI response message.
+          requirement_level: recommended
+          fields:
+            - id: content
+              type: undefined
+              stability: experimental
+              brief: >
+                The contents of the assistant message.
+              examples: ["The weather in Paris is rainy and overcast, with temperatures around 57°F"]
+              requirement_level: opt_in
+            - id: role
+              type: string
+              stability: experimental
+              brief: >
+                The actual role of the message author as passed in the message.
+              examples: ["assistant", "bot"]
+              requirement_level:
+                conditionally_required: if available and not equal to `assistant`.
+        - id: tool_calls
+          type: map[]
+          stability: experimental
+          brief: >
+            The tool calls generated by the model, such as function calls.
+          requirement_level:
+            conditionally_required: if available
+          fields:
+            - id: id
+              type: string
+              stability: experimental
+              brief: >
+                The id of the tool call.
+              examples: ["call_mszuSIzqtI65i1wAUOE8w5H4"]
+              requirement_level: required
+            - id: type
+              type: enum
+              members:
+                - id: function
+                  value: 'function'
+                  brief: Function
+              stability: experimental
+              brief: >
+                The type of the tool.
+              requirement_level: required
+            - id: function
+              type: map
+              stability: experimental
+              brief: >
+                The function that the model called.
+              requirement_level: required
+              fields:
+                - id: name
+                  type: string
+                  stability: experimental
+                  brief: >
+                    The name of the function.
+                  examples: ["get_weather"]
+                  requirement_level: required
+                - id: arguments
+                  type: undefined
+                  stability: experimental
+                  brief: >
+                    The arguments of the function as provided in the LLM response.
+                  note: >
+                    Models usually return arguments as a JSON string. In this case, it's
+                    RECOMMENDED to provide arguments as is without attempting to deserialize them.
+
+                    Semantic conventions for individual systems MAY specify a different type for
+                    arguments field.
+                  examples: ['{\"location\": \"Paris\"}']
+                  requirement_level: opt_in

templates/registry/markdown/body_field_table.j2

@@ -6,7 +6,10 @@
 {% macro flatten(fields, ns, depth) %}{% if fields %}{% for f in fields | sort(attribute="id") %}
 {% set ns.flat = [ns.flat, [{'field':f,'depth':depth}]] | flatten %}{% if f.fields %}{% set _= flatten(f.fields, ns, depth + 1) %}{% endif %}
 {% endfor %}{% endif %}{% endmacro %}
-{% macro field_name(field, depth) %}{% set name= " " * 2 * depth ~ '`' ~ field.id ~ '`' %}{% if field.type == "map" %}{{ name ~ ":"}}{% else %}{{ name }}{% endif %}{% endmacro %}
+{% macro field_name(field, depth) -%}
+{%- set name= " " * 2 * depth ~ '`' ~ field.id ~ '`' -%}
+{%- if (field.type == "map") or (field.type == "map[]") %}{{ name ~ ":"}}{% else -%}
+{{ name }}{% endif %}{% endmacro %}
 {#- Macro for creating body table -#}
 {% macro generate(fields) %}{% if (fields | length > 0) %}{% set ns = namespace(flat=[])%}{% set _ = flatten(fields, ns, 0) %}| Body Field  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|