The genai_message_roles function extracts an array of all message roles from a GenAI conversation. This provides a sequence view of conversation participants, showing the order and types of messages (user, assistant, system, tool, etc.).
You can use this function to analyze conversation patterns, validate conversation structure, detect role sequences, or understand conversation flow and complexity.
For users of other query languages
If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.
In Splunk SPL, you would extract the role field from all messages in an array.
['ai-logs']
| extend roles = genai_message_roles(messages)In ANSI SQL, you would unnest the array and collect roles into an array.
['ai-logs']
| extend roles = genai_message_roles(messages)Usage
Syntax
genai_message_roles(messages)Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| messages | dynamic | Yes | An array of message objects from a GenAI conversation. Each message typically contains role and content fields. |
Returns
Returns a dynamic array containing all the roles in the conversation in their original order (for example, ['system', 'user', 'assistant', 'user', 'assistant']).
Example
Extract all message roles from a GenAI conversation to understand the conversation structure.
Query
['otel-demo-genai']
| extend roles = genai_message_roles(['attributes.gen_ai.input.messages'])
| extend role_sequence = tostring(roles)
| summarize conversation_count = count() by role_sequence
| top 5 by conversation_countOutput
| role_sequence | conversation_count |
|---|---|
| ["system","user","assistant"] | 850 |
| ["system","user","assistant","user","assistant"] | 345 |
| ["user","assistant"] | 189 |
This query identifies the most common conversation patterns, helping you understand typical user interaction flows.
List of related functions
- genai_get_role: Gets the role at a specific index. Use this when you need a specific role rather than the full sequence.
- genai_conversation_turns: Counts conversation turns. Use this for a numerical metric of conversation length.
- genai_get_content_by_role: Gets content for a specific role. Use this after identifying roles of interest.
- array_length: Returns the number of messages. Apply this to the roles array to count messages.
- array_index_of: Finds the position of a role. Use this to detect if specific roles exist in the conversation.