genai_message_roles

You can use this function to analyze conversation patterns, validate conversation structure, detect role sequences, or understand conversation flow and complexity.

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_count

Run in Playground

Output

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.

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.

Other query languages#

Splunk SPL users

In Splunk SPL, you would extract the role field from all messages in an array.

Splunk example

| eval roles=mvindex(role, 0, mvcount(role))

APL equivalent

['ai-logs']
| extend roles = genai_message_roles(messages)

ANSI SQL users

In ANSI SQL, you would unnest the array and collect roles into an array.

SQL example

SELECT
  conversation_id,
  ARRAY_AGG(role ORDER BY msg_index) as roles
FROM conversations
CROSS JOIN UNNEST(messages) WITH OFFSET AS msg_index
GROUP BY conversation_id