genai_get_role

You can use this function to validate conversation structure, analyze message patterns, verify conversation flow, or process conversations based on role sequences.

Usage#

Syntax#

genai_get_role(messages, index)

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.
index	long	Yes	The zero-based position of the message whose role you want to retrieve. Use 0 for the first message, 1 for the second, etc.

Returns#

Returns a string containing the role of the message at the specified index (such as 'user', 'assistant', 'system', 'tool', 'function'), or an empty string if the index is out of bounds.

Example#

Get the role of the first message in a GenAI conversation.

Query

['otel-demo-genai']
| extend first_role = genai_get_role(['attributes.gen_ai.input.messages'], 0)
| summarize conversations_with_system = countif(first_role == 'system'), total_conversations = count()

Run in Playground

Output

conversations_with_system	total_conversations
1250	1450

This query verifies that most conversations are properly initialized with system prompts.

genai_get_content_by_index: Gets content at a specific index. Combine with genai_get_role to understand both role and content at positions.
genai_message_roles: Lists all roles in the conversation. Use this to get a complete picture of all roles rather than checking individual positions.
genai_get_content_by_role: Gets content filtered by role. Use this when you need content from a specific role type.
array_length: Returns the total number of messages. Use this to validate index bounds before accessing positions.

Other query languages#

Splunk SPL users

In Splunk SPL, you would use mvindex to access the role field at a specific position.

Splunk example

| eval message_role=mvindex(role, 2)

APL equivalent

['ai-logs']
| extend message_role = genai_get_role(messages, 2)

ANSI SQL users

In ANSI SQL, you would unnest the array and access the role at a specific offset.

SQL example

SELECT
  conversation_id,
  role as message_role
FROM conversations
CROSS JOIN UNNEST(messages) WITH OFFSET AS pos
WHERE pos = 2