KQL Search

Query Details

06 Cloudappevents Agent Execution Spans

Query

CloudAppEvents
| where Timestamp > ago(LookbackWindow)
| where ActionType in (AgentSpanActionTypes)
| where isnotempty(RawEventData)
| extend Operation = tostring(RawEventData.Operation)
| extend AgentIdentityId = coalesce(tostring(RawEventData.TargetAgentId), tostring(RawEventData.AgentId), tostring(RawEventData.AgentId))
| extend AgentBlueprintId = coalesce(tostring(RawEventData.TargetAgentBlueprintID), tostring(RawEventData.AgentBlueprintId))
| extend ConversationId = tostring(RawEventData.ConversationId)
| extend ChannelName = tostring(RawEventData.ChannelName)
| extend ToolName = tostring(RawEventData.ToolName)
| extend ToolType = tostring(RawEventData.ToolType)
| extend ToolId = tostring(RawEventData.ToolId)
| extend ClientIP = tostring(RawEventData.ClientIP)
| extend UserKey = tostring(RawEventData.UserKey)
| extend UserId = tostring(RawEventData.UserId)
| extend SpanId = tostring(RawEventData.OpId)
| extend ParentSpanId = tostring(RawEventData.ParentId)
| extend CompletionTime = todatetime(RawEventData.CompletionTime)
| extend ErrorMessage = tostring(RawEventData.ErrorMessage)
| extend ErrorType = tostring(RawEventData.ErrorType)
| extend ResultType = case(
    isnotempty(ErrorType) or isnotempty(ErrorMessage), "error",
    "success"
    // NOTE: there is no confirmed "denied" (authorization-failure) signal in
    // this attribute set today -- ErrorType is a free-form OTel status
    // category, not an HTTP-style status code. Do not assume ErrorType values
    // map to "denied" without inspecting real ErrorType values in your tenant first.
)
| extend PermissionUsed = iff(Operation == "execute_tool" and isnotempty(ToolName), strcat(ToolType, ":", ToolName), "")
| project
    Timestamp,
    AgentIdentityId,
    AgentBlueprintId,
    Operation,
    ConversationId,
    ChannelName,
    ToolName, ToolType, ToolId,
    PermissionUsed,
    ClientIP,
    UserKey, UserId,
    SpanId, ParentSpanId,
    CompletionTime,
    ResultType,
    ErrorType, ErrorMessage
| order by Timestamp desc

About this query

Explanation

This query is designed to analyze and extract information about agent execution spans from the CloudAppEvents table, which contains telemetry data from Microsoft Agent 365. Here's a simplified breakdown of what the query does:

  1. Initial Setup:

    • The query is part of a series of queries (Phase 3, query 6 of 7) aimed at analyzing agent execution data.
    • It uses data from the CloudAppEvents table, which requires Microsoft Agent 365 telemetry to be configured.

  2. Step 1 - Schema Discovery:

    • Before filtering the data, it first identifies which ActionType values in your tenant contain the relevant agent span data. This is done by checking for specific field names (AgentBlueprintId or TargetAgentBlueprintID) within the RawEventData.
    • The result of this step helps determine the correct ActionType values to use in the main query.

  3. Main Query:

    • Lookback Window: The query looks at data from the past 90 days (or another specified period).
    • Filter by ActionType: It filters events based on the ActionType values identified in Step 1. - Extract and Transform Data: The query extracts various fields from the RawEventData JSON, such as Operation, AgentIdentityId, AgentBlueprintId, ConversationId, ChannelName, ToolName, ToolType, ToolId, ClientIP, UserKey, UserId, SpanId, ParentSpanId, CompletionTime, ErrorMessage, and ErrorType.
    • Determine Result Type: It classifies the result as "error" if there is an ErrorType or ErrorMessage, otherwise as "success".
    • Permission Used: For operations labeled as "execute_tool", it constructs a PermissionUsed field using ToolType and ToolName.

  4. Output:

    • The query projects a set of fields to display, including Timestamp, AgentIdentityId, AgentBlueprintId, Operation, ConversationId, ChannelName, ToolName, ToolType, ToolId, PermissionUsed, ClientIP, UserKey, UserId, SpanId, ParentSpanId, CompletionTime, ResultType, ErrorType, and ErrorMessage.
    • The results are ordered by Timestamp in descending order.

In summary, this query is used to extract and analyze detailed information about agent execution activities from the CloudAppEvents table, focusing on specific telemetry data related to Microsoft Agent 365.