1# KQL Templates — GenAI Trace Query Reference
2 
3Ready-to-use KQL templates for querying GenAI OpenTelemetry traces in Application Insights.
4 
5**Table of Contents:** [App Insights Table Mapping](#app-insights-table-mapping) · [Key GenAI OTel Attributes](#key-genai-otel-attributes) · [Span Correlation](#span-correlation) · [Hosted Agent Attributes](#hosted-agent-attributes) · [Response ID Formats](#response-id-formats) · [Common Query Templates](#common-query-templates) · [OTel Reference Links](#otel-reference-links)
6 
7## App Insights Table Mapping
8 
9| App Insights Table | GenAI Data |
10|-------------------|------------|
11| `dependencies` | GenAI spans: LLM inference (`chat`), tool execution (`execute_tool`), agent invocation (`invoke_agent`) |
12| `requests` | Incoming HTTP requests to the agent endpoint. For hosted agents, also carries `gen_ai.agent.name` (Foundry name) and `azure.ai.agentserver.*` attributes — **preferred entry point** for agent-name filtering |
13| `customEvents` | GenAI evaluation results (`gen_ai.evaluation.result`) — scores, labels, explanations |
14| `traces` | Log events, including GenAI events (input/output messages) |
15| `exceptions` | Error details with stack traces |
16 
17## Key GenAI OTel Attributes
18 
19Stored in `customDimensions` on `dependencies` spans:
20 
21| Attribute | Description | Example |
22|-----------|-------------|---------|
23| `gen_ai.operation.name` | Operation type | `chat`, `invoke_agent`, `execute_tool`, `create_agent` |
24| `gen_ai.conversation.id` | Conversation/session ID | `conv_5j66UpCpwteGg4YSxUnt7lPY` |
25| `gen_ai.response.id` | Response ID | `chatcmpl-123` |
26| `gen_ai.agent.name` | Agent name | `my-support-agent` |
27| `gen_ai.agent.id` | Agent identifier | `asst_abc123` |
28| `gen_ai.request.model` | Requested model | `gpt-4o` |
29| `gen_ai.response.model` | Actual model used | `gpt-4o-2024-05-13` |
30| `gen_ai.usage.input_tokens` | Input token count | `450` |
31| `gen_ai.usage.output_tokens` | Output token count | `120` |
32| `gen_ai.response.finish_reasons` | Stop reasons | `["stop"]`, `["tool_calls"]` |
33| `error.type` | Error classification | `timeout`, `rate_limited`, `content_filter` |
34| `gen_ai.provider.name` | Provider | `azure.ai.openai`, `openai` |
35| `gen_ai.input.messages` | Full input messages (JSON array) — on `invoke_agent` spans | `[{"role":"user","parts":[{"type":"text","content":"..."}]}]` |
36| `gen_ai.output.messages` | Full output messages (JSON array) — on `invoke_agent` spans | `[{"role":"assistant","parts":[{"type":"text","content":"..."}]}]` |
37 
38Stored in `customDimensions` on `customEvents` (name == `gen_ai.evaluation.result`):
39 
40| Attribute | Description | Example |
41|-----------|-------------|---------|
42| `gen_ai.evaluation.name` | Evaluator name | `Relevance`, `IntentResolution` |
43| `gen_ai.evaluation.score.value` | Numeric score | `4.0` |
44| `gen_ai.evaluation.score.label` | Human-readable label | `pass`, `fail`, `relevant` |
45| `gen_ai.evaluation.explanation` | Free-form explanation | `"Response lacks detail..."` |
46| `gen_ai.response.id` | Correlates to the evaluated span | `chatcmpl-123` |
47| `gen_ai.conversation.id` | Correlates to conversation | `conv_5j66...` |
48 
49> **Correlation:** Eval results do NOT link via id-parentId. Use `gen_ai.conversation.id` and/or `gen_ai.response.id` to join with `dependencies` spans.
50 
51## Span Correlation
52 
53| Field | Purpose |
54|-------|---------|
55| `operation_Id` | Trace ID — groups all spans in one request |
56| `id` | Span ID — unique identifier for this span |
57| `operation_ParentId` | Parent span ID — use with `id` to build span trees |
58 
59### Operation_Id Join (requests → dependencies)
60 
61Use `requests` as the hosted-agent entry point, then carry `operation_Id` forward as the trace key when joining into `dependencies`, `traces`, or `customEvents`:
62 
63```kql
64let agentRequests = materialize(
65    requests
66| where timestamp > ago(7d)
67| extend
68    foundryAgentName = coalesce(
69        tostring(customDimensions["gen_ai.agent.name"]),
70        tostring(customDimensions["azure.ai.agentserver.agent_name"])
71    ),
72    agentId = tostring(customDimensions["gen_ai.agent.id"]),
73    agentNameFromId = tostring(split(agentId, ":")[0]),
74    agentVersion = iff(agentId contains ":", tostring(split(agentId, ":")[1]), ""),
75    conversationId = coalesce(
76        tostring(customDimensions["gen_ai.conversation.id"]),
77        tostring(customDimensions["azure.ai.agentserver.conversation_id"]),
78        operation_Id
79    )
80| where foundryAgentName == "<foundry-agent-name>"
81    or agentNameFromId == "<foundry-agent-name>"
82| project operation_Id, conversationId, agentVersion
83);
84dependencies
85| where timestamp > ago(7d)
86| where isnotempty(customDimensions["gen_ai.operation.name"])
87| join kind=inner agentRequests on operation_Id
88| extend
89    operation = tostring(customDimensions["gen_ai.operation.name"]),
90    model = tostring(customDimensions["gen_ai.request.model"])
91| project timestamp, duration, success, operation, model, conversationId, agentVersion, operation_Id
92| order by timestamp desc
93```
94 
95## Hosted Agent Attributes
96 
97Stored in `customDimensions` on **both `requests` and `traces`** tables (NOT on `dependencies` spans):
98 
99| Attribute | Description | Example |
100|-----------|-------------|---------|
101| `azure.ai.agentserver.agent_name` | Hosted agent name | `hosted-agent-022-001` |
102| `azure.ai.agentserver.agent_id` | Internal agent ID | `code-asst-xmwokux85uqc7fodxejaxa` |
103| `azure.ai.agentserver.conversation_id` | Conversation ID | `conv_d7ab624de92d...` |
104| `azure.ai.agentserver.response_id` | Response ID (caresp format) | `caresp_d7ab624de92d...` |
105 
106> **Important:** Use `requests` as the preferred entry point for agent-name filtering — it has both `azure.ai.agentserver.agent_name` and `gen_ai.agent.name` with the Foundry-level name. To reach downstream spans and related telemetry, carry `operation_Id` forward from the filtered request set and join other tables on that trace key.
107 
108> 💡 **Version enrichment:** Some hosted-agent `requests` telemetry emits `gen_ai.agent.id` in `<foundry-agent-name>:<version>` format. When that delimiter is present, split on `:` to recover `agentVersion`; if it is absent, keep filtering on the requests-scoped name fields and leave version blank.
109 
110> ⚠️ **`gen_ai.agent.name` means different things on different tables:**
111> - On `requests`: the **Foundry agent name** (user-visible) → e.g., `hosted-agent-022-001`
112> - On `dependencies`: the **code-level class name** → e.g., `BingSearchAgent`
113>
114> **Always start from `requests`** when filtering by the Foundry agent name the user knows.
115 
116## Response ID Formats
117 
118| Agent Type | Prefix | Example |
119|------------|--------|---------|
120| Hosted agent (AgentServer) | `caresp_` | `caresp_d7ab624de92da637008Rhr4U4E1y9FSE...` |
121| Prompt agent (Foundry Responses API) | `resp_` | `resp_4e2f8b016b5a0dad00697bd3c4c1b881...` |
122| Azure OpenAI chat completions | `chatcmpl-` | `chatcmpl-abc123def456` |
123 
124When searching by response ID, use the appropriate prefix to narrow results. The `gen_ai.response.id` attribute appears on `dependencies` spans (for `chat` operations) and in `customEvents` (for evaluation results).
125 
126## Common Query Templates
127 
128### Overview — Conversations in last 24h
129```kql
130dependencies
131| where timestamp > ago(24h)
132| where isnotempty(customDimensions["gen_ai.operation.name"])
133| summarize
134    spanCount = count(),
135    errorCount = countif(success == false),
136    avgDuration = avg(duration),
137    totalInputTokens = sum(toint(customDimensions["gen_ai.usage.input_tokens"])),
138    totalOutputTokens = sum(toint(customDimensions["gen_ai.usage.output_tokens"]))
139  by bin(timestamp, 1h)
140| order by timestamp desc
141```
142 
143### Error Rate by Operation
144```kql
145dependencies
146| where timestamp > ago(24h)
147| where isnotempty(customDimensions["gen_ai.operation.name"])
148| summarize
149    total = count(),
150    errors = countif(success == false),
151    errorRate = round(100.0 * countif(success == false) / count(), 1)
152  by operation = tostring(customDimensions["gen_ai.operation.name"])
153| order by errorRate desc
154```
155 
156### Token Usage by Model
157```kql
158dependencies
159| where timestamp > ago(24h)
160| where customDimensions["gen_ai.operation.name"] == "chat"
161| summarize
162    calls = count(),
163    totalInput = sum(toint(customDimensions["gen_ai.usage.input_tokens"])),
164    totalOutput = sum(toint(customDimensions["gen_ai.usage.output_tokens"])),
165    avgInput = avg(todouble(customDimensions["gen_ai.usage.input_tokens"])),
166    avgOutput = avg(todouble(customDimensions["gen_ai.usage.output_tokens"]))
167  by model = tostring(customDimensions["gen_ai.request.model"])
168| order by totalInput desc
169```
170 
171### Tool Call Details
172```kql
173dependencies
174| where operation_Id == "<operation_id>"
175| where customDimensions["gen_ai.operation.name"] == "execute_tool"
176| project timestamp, duration, success,
177    toolName = tostring(customDimensions["gen_ai.tool.name"]),
178    toolType = tostring(customDimensions["gen_ai.tool.type"]),
179    toolCallId = tostring(customDimensions["gen_ai.tool.call.id"]),
180    toolArgs = tostring(customDimensions["gen_ai.tool.call.arguments"]),
181    toolResult = tostring(customDimensions["gen_ai.tool.call.result"])
182| order by timestamp asc
183```
184 
185Key tool attributes:
186 
187| Attribute | Description | Example |
188|-----------|-------------|---------|
189| `gen_ai.tool.name` | Tool function name | `remote_functions.bing_grounding`, `python` |
190| `gen_ai.tool.type` | Tool type | `extension`, `function` |
191| `gen_ai.tool.call.id` | Unique call ID | `call_db64aa6a004a...` |
192| `gen_ai.tool.call.arguments` | JSON arguments passed | `{"query": "latest AI news"}` |
193| `gen_ai.tool.call.result` | Tool output (may be truncated) | `<<ImageDisplayed>>` |
194 
195### Evaluation Results by Conversation
196```kql
197customEvents
198| where timestamp > ago(24h)
199| where name == "gen_ai.evaluation.result"
200| extend
201    evalName = tostring(customDimensions["gen_ai.evaluation.name"]),
202    score = todouble(customDimensions["gen_ai.evaluation.score.value"]),
203    label = tostring(customDimensions["gen_ai.evaluation.score.label"]),
204    conversationId = tostring(customDimensions["gen_ai.conversation.id"])
205| summarize
206    evalCount = count(),
207    avgScore = avg(score),
208    failCount = countif(label == "fail" or label == "not_relevant" or label == "incorrect"),
209    evaluators = make_set(evalName)
210  by conversationId
211| order by failCount desc
212```
213 
214> For detailed eval queries by response ID or conversation ID, see [Eval Correlation](eval-correlation.md).
215 
216## OTel Reference Links
217 
218- [GenAI Spans](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/)
219- [GenAI Agent Spans](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/)
220- [GenAI Events](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-events/)
221- [GenAI Metrics](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-metrics/)
222