Skip to content

Commit 445170d

Browse files
paolosalvatoriremotesynth
paolosalvatori
and
remotesynth
authored
Azure Docs: Azure Monitor Scheduled Query Rules (#593)
Co-authored-by: Brian Rinaldi <brian.rinaldi@gmail.com>
1 parent 352c077 commit 445170d

1 file changed

Lines changed: 297 additions & 0 deletions

File tree

‎src/content/docs/azure/services/scheduled-query-rules.mdx‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
---
2+
title: "Scheduled Query Rules"
3+
description: Get started with Azure Monitor Scheduled Query Rules on LocalStack
4+
template: doc
5+
---
6+
7+
import AzureFeatureCoverage from "../../../../components/feature-coverage/AzureFeatureCoverage";
8+
9+
## Introduction
10+
11+
Azure Monitor Scheduled Query Rules (SQR) run KQL log queries on a defined schedule against data in one or more scopes (for example a Log Analytics workspace).
12+
When query results meet a configured condition, an alert is fired and routed through an Action Group.
13+
Scheduled Query Rules are commonly used to detect patterns in application logs, audit events, and custom metrics that cannot be captured by standard metric alerts. For more information, see [Log alerts in Azure Monitor](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-log).
14+
15+
LocalStack for Azure provides a local environment for building and testing applications that make use of Azure Monitor Scheduled Query Rules.
16+
The supported APIs are available on our [API Coverage section](#api-coverage), which provides information on the extent of Scheduled Query Rules' integration with LocalStack.
17+
18+
## Getting started
19+
20+
This guide walks you through creating a Scheduled Query Rule that targets a Log Analytics workspace.
21+
22+
Launch LocalStack using your preferred method. For more information, see [Introduction to LocalStack for Azure](/azure/getting-started/). Once the container is running, enable Azure CLI interception by running:
23+
24+
```bash
25+
azlocal start-interception
26+
```
27+
28+
This command points the `az` CLI away from the public Azure management REST API and toward the LocalStack for Azure emulator API.
29+
To revert this configuration, run:
30+
31+
```bash
32+
azlocal stop-interception
33+
```
34+
35+
This reconfigures the `az` CLI to send commands to the official Azure management REST API.
36+
37+
### Create a resource group
38+
39+
Create a resource group to hold all resources created in this guide:
40+
41+
```bash
42+
az group create --name rg-sqr-demo --location westeurope
43+
```
44+
45+
```bash title="Output"
46+
{
47+
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-sqr-demo",
48+
"location": "westeurope",
49+
"name": "rg-sqr-demo",
50+
"properties": { "provisioningState": "Succeeded" },
51+
"type": "Microsoft.Resources/resourceGroups"
52+
}
53+
```
54+
55+
### Create a Log Analytics workspace
56+
57+
Create a Log Analytics workspace to use as the scheduled query target:
58+
59+
```bash
60+
az monitor log-analytics workspace create \
61+
--name my-workspace \
62+
--resource-group rg-sqr-demo \
63+
--location westeurope
64+
```
65+
66+
```bash title="Output"
67+
{
68+
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-sqr-demo/providers/Microsoft.OperationalInsights/workspaces/my-workspace",
69+
"location": "westeurope",
70+
"name": "my-workspace",
71+
"provisioningState": "Succeeded",
72+
"resourceGroup": "rg-sqr-demo",
73+
"sku": { "name": "PerGB2018" },
74+
"type": "Microsoft.OperationalInsights/workspaces"
75+
}
76+
```
77+
78+
### Create an action group
79+
80+
Create an action group to serve as the notification target when the alert fires:
81+
82+
```bash
83+
az monitor action-group create \
84+
--name my-ag \
85+
--resource-group rg-sqr-demo \
86+
--short-name myag \
87+
--action email admin admin@example.com
88+
```
89+
90+
```bash title="Output"
91+
{
92+
"emailReceivers": [
93+
{ "emailAddress": "admin@example.com", "name": "admin", "useCommonAlertSchema": false }
94+
],
95+
"enabled": true,
96+
"groupShortName": "myag",
97+
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-sqr-demo/providers/microsoft.insights/actionGroups/my-ag",
98+
"location": "Global",
99+
"name": "my-ag",
100+
"resourceGroup": "rg-sqr-demo",
101+
"type": "Microsoft.Insights/ActionGroups"
102+
}
103+
```
104+
105+
### Create a scheduled query rule
106+
107+
Retrieve the workspace and action group resource IDs, then create a scheduled query rule with a count-based condition on the `Heartbeat` table (in Azure, the rule would evaluate this KQL on the schedule you set and fire when the condition is met):
108+
109+
```bash
110+
WORKSPACE_ID=$(az monitor log-analytics workspace show \
111+
--workspace-name my-workspace \
112+
--resource-group rg-sqr-demo \
113+
--query id \
114+
--output tsv)
115+
116+
AG_ID=$(az monitor action-group show \
117+
--name my-ag \
118+
--resource-group rg-sqr-demo \
119+
--query id \
120+
--output tsv)
121+
122+
az monitor scheduled-query create \
123+
--name my-sqr \
124+
--resource-group rg-sqr-demo \
125+
--scopes "$WORKSPACE_ID" \
126+
--condition "count 'Placeholder_1' > 5" \
127+
--condition-query 'Placeholder_1="Heartbeat | where TimeGenerated > ago(5m)"' \
128+
--description "Alert on Heartbeat count" \
129+
--action-groups "$AG_ID" \
130+
--evaluation-frequency 5m \
131+
--window-size 5m \
132+
--severity 2
133+
```
134+
135+
```bash title="Output"
136+
{
137+
"actions": {
138+
"actionGroups": [
139+
"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-sqr-demo/providers/microsoft.insights/actionGroups/my-ag"
140+
]
141+
},
142+
"criteria": {
143+
"allOf": [
144+
{
145+
"operator": "GreaterThan",
146+
"query": "Heartbeat | where TimeGenerated > ago(5m)",
147+
"threshold": 5.0,
148+
"timeAggregation": "Count"
149+
}
150+
]
151+
},
152+
"description": "Alert on Heartbeat count",
153+
"enabled": true,
154+
"evaluationFrequency": "PT5M",
155+
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-sqr-demo/providers/microsoft.insights/scheduledqueryrules/my-sqr",
156+
"location": "westeurope",
157+
"name": "my-sqr",
158+
"resourceGroup": "rg-sqr-demo",
159+
"scopes": [
160+
"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-sqr-demo/providers/Microsoft.OperationalInsights/workspaces/my-workspace"
161+
],
162+
"severity": 2,
163+
"type": "microsoft.insights/scheduledqueryrules",
164+
"windowSize": "PT5M"
165+
}
166+
```
167+
168+
### Show and list query rules
169+
170+
Retrieve the details of the scheduled query rule and list all rules in the resource group:
171+
172+
```bash
173+
az monitor scheduled-query show \
174+
--name my-sqr \
175+
--resource-group rg-sqr-demo
176+
```
177+
178+
```bash title="Output"
179+
{
180+
"actions": {
181+
"actionGroups": [
182+
"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-sqr-demo/providers/microsoft.insights/actionGroups/my-ag"
183+
]
184+
},
185+
"criteria": {
186+
"allOf": [
187+
{
188+
"operator": "GreaterThan",
189+
"query": "Heartbeat | where TimeGenerated > ago(5m)",
190+
"threshold": 5.0,
191+
"timeAggregation": "Count"
192+
}
193+
]
194+
},
195+
"description": "Alert on Heartbeat count",
196+
"enabled": true,
197+
"evaluationFrequency": "PT5M",
198+
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-sqr-demo/providers/microsoft.insights/scheduledqueryrules/my-sqr",
199+
"location": "westeurope",
200+
"name": "my-sqr",
201+
"resourceGroup": "rg-sqr-demo",
202+
"scopes": [
203+
"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-sqr-demo/providers/Microsoft.OperationalInsights/workspaces/my-workspace"
204+
],
205+
"severity": 2,
206+
"type": "microsoft.insights/scheduledqueryrules",
207+
"windowSize": "PT5M"
208+
}
209+
```
210+
211+
212+
Then list all scheduled query rules in the resource group:
213+
214+
```bash
215+
az monitor scheduled-query list \
216+
--resource-group rg-sqr-demo
217+
```
218+
219+
```bash title="Output"
220+
[
221+
{
222+
"actions": {
223+
"actionGroups": [
224+
"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-sqr-demo/providers/microsoft.insights/actionGroups/my-ag"
225+
]
226+
},
227+
"criteria": {
228+
"allOf": [
229+
{
230+
"operator": "GreaterThan",
231+
"query": "Heartbeat | where TimeGenerated > ago(5m)",
232+
"threshold": 5.0,
233+
"timeAggregation": "Count"
234+
}
235+
]
236+
},
237+
"enabled": true,
238+
"evaluationFrequency": "PT5M",
239+
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-sqr-demo/providers/microsoft.insights/scheduledqueryrules/my-sqr",
240+
"location": "westeurope",
241+
"name": "my-sqr",
242+
"resourceGroup": "rg-sqr-demo",
243+
"scopes": [
244+
"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-sqr-demo/providers/Microsoft.OperationalInsights/workspaces/my-workspace"
245+
],
246+
"severity": 2,
247+
"type": "microsoft.insights/scheduledqueryrules",
248+
"windowSize": "PT5M"
249+
}
250+
]
251+
```
252+
253+
### Delete and verify
254+
255+
Delete the resource and confirm it no longer appears in the list:
256+
257+
```bash
258+
az monitor scheduled-query delete \
259+
--name my-sqr \
260+
--resource-group rg-sqr-demo \
261+
--yes
262+
```
263+
264+
Then list all scheduled query rules to confirm the resource group is now empty:
265+
266+
```bash
267+
az monitor scheduled-query list --resource-group rg-sqr-demo
268+
```
269+
270+
```bash title="Output"
271+
[]
272+
```
273+
274+
## Features
275+
276+
- **Scheduled Query Rule lifecycle:** Create, read, list, update, and delete SQR resources.
277+
- **KQL query storage:** Store the KQL query definition within the rule (not executed).
278+
- **Condition configuration:** Define threshold, operator, time aggregation, and evaluation period.
279+
- **Action group references:** Associate one or more action groups with a query rule.
280+
- **Severity levels:** Set alert severity from 0 (critical) to 4 (verbose), consistent with [Azure CLI `az monitor scheduled-query`](https://learn.microsoft.com/en-us/cli/azure/monitor/scheduled-query).
281+
- **Evaluation frequency and window size:** Set how often the rule runs and the aggregation window (`5m`-style values in the CLI; the API represents these as ISO 8601 durations such as `PT5M`). See the REST API property reference for [`scheduledQueryRules`](https://learn.microsoft.com/en-us/rest/api/monitor/scheduled-query-rules/create-or-update).
282+
- **Multiple scopes:** Provide several scope resource IDs when your scenario requires it (the CLI documents [constraints on `scopes`](https://learn.microsoft.com/en-us/cli/azure/monitor/scheduled-query?view=azure-cli-latest#az-monitor-scheduled-query-create)).
283+
284+
## Limitations
285+
286+
- **No KQL execution:** The query defined in the rule is never run against Log Analytics data.
287+
- **No alert firing:** Alert thresholds are never evaluated and no alerts are triggered.
288+
- **No notifications dispatched:** Action group notifications are not sent (unlike Azure, where a firing rule invokes the configured action groups).
289+
- **No alert history:** Alert instance history and state transitions are not recorded.
290+
291+
## Samples
292+
293+
Explore end-to-end examples in the [LocalStack for Azure Samples](https://github.com/localstack/localstack-azure-samples) repository.
294+
295+
## API Coverage
296+
297+
<AzureFeatureCoverage service="Microsoft.Insights" client:load />

0 commit comments

Comments
 (0)