Azure Monitor Query Py

1---
2name: azure-monitor-query-py
3description: |
4  Azure Monitor Query SDK for Python. Use for querying Log Analytics workspaces and Azure Monitor metrics.
5  Triggers: "azure-monitor-query", "LogsQueryClient", "MetricsQueryClient", "Log Analytics", "Kusto queries", "Azure metrics".
6package: azure-monitor-query
7---
8 
9# Azure Monitor Query SDK for Python
10 
11Query logs and metrics from Azure Monitor and Log Analytics workspaces.
12 
13## Installation
14 
15```bash
16pip install azure-monitor-query
17```
18 
19## Environment Variables
20 
21```bash
22# Log Analytics
23AZURE_LOG_ANALYTICS_WORKSPACE_ID=<workspace-id>
24 
25# Metrics
26AZURE_METRICS_RESOURCE_URI=/subscriptions/<sub>/resourceGroups/<rg>/providers/<provider>/<type>/<name>
27```
28 
29## Authentication
30 
31```python
32from azure.identity import DefaultAzureCredential
33 
34credential = DefaultAzureCredential()
35```
36 
37## Logs Query Client
38 
39### Basic Query
40 
41```python
42from azure.monitor.query import LogsQueryClient
43from datetime import timedelta
44 
45client = LogsQueryClient(credential)
46 
47query = """
48AppRequests
49| where TimeGenerated > ago(1h)
50| summarize count() by bin(TimeGenerated, 5m), ResultCode
51| order by TimeGenerated desc
52"""
53 
54response = client.query_workspace(
55    workspace_id=os.environ["AZURE_LOG_ANALYTICS_WORKSPACE_ID"],
56    query=query,
57    timespan=timedelta(hours=1)
58)
59 
60for table in response.tables:
61    for row in table.rows:
62        print(row)
63```
64 
65### Query with Time Range
66 
67```python
68from datetime import datetime, timezone
69 
70response = client.query_workspace(
71    workspace_id=workspace_id,
72    query="AppRequests | take 10",
73    timespan=(
74        datetime(2024, 1, 1, tzinfo=timezone.utc),
75        datetime(2024, 1, 2, tzinfo=timezone.utc)
76    )
77)
78```
79 
80### Convert to DataFrame
81 
82```python
83import pandas as pd
84 
85response = client.query_workspace(workspace_id, query, timespan=timedelta(hours=1))
86 
87if response.tables:
88    table = response.tables[0]
89    df = pd.DataFrame(data=table.rows, columns=[col.name for col in table.columns])
90    print(df.head())
91```
92 
93### Batch Query
94 
95```python
96from azure.monitor.query import LogsBatchQuery
97 
98queries = [
99    LogsBatchQuery(workspace_id=workspace_id, query="AppRequests | take 5", timespan=timedelta(hours=1)),
100    LogsBatchQuery(workspace_id=workspace_id, query="AppExceptions | take 5", timespan=timedelta(hours=1))
101]
102 
103responses = client.query_batch(queries)
104 
105for response in responses:
106    if response.tables:
107        print(f"Rows: {len(response.tables[0].rows)}")
108```
109 
110### Handle Partial Results
111 
112```python
113from azure.monitor.query import LogsQueryStatus
114 
115response = client.query_workspace(workspace_id, query, timespan=timedelta(hours=24))
116 
117if response.status == LogsQueryStatus.PARTIAL:
118    print(f"Partial results: {response.partial_error}")
119elif response.status == LogsQueryStatus.FAILURE:
120    print(f"Query failed: {response.partial_error}")
121```
122 
123## Metrics Query Client
124 
125### Query Resource Metrics
126 
127```python
128from azure.monitor.query import MetricsQueryClient
129from datetime import timedelta
130 
131metrics_client = MetricsQueryClient(credential)
132 
133response = metrics_client.query_resource(
134    resource_uri=os.environ["AZURE_METRICS_RESOURCE_URI"],
135    metric_names=["Percentage CPU", "Network In Total"],
136    timespan=timedelta(hours=1),
137    granularity=timedelta(minutes=5)
138)
139 
140for metric in response.metrics:
141    print(f"{metric.name}:")
142    for time_series in metric.timeseries:
143        for data in time_series.data:
144            print(f"  {data.timestamp}: {data.average}")
145```
146 
147### Aggregations
148 
149```python
150from azure.monitor.query import MetricAggregationType
151 
152response = metrics_client.query_resource(
153    resource_uri=resource_uri,
154    metric_names=["Requests"],
155    timespan=timedelta(hours=1),
156    aggregations=[
157        MetricAggregationType.AVERAGE,
158        MetricAggregationType.MAXIMUM,
159        MetricAggregationType.MINIMUM,
160        MetricAggregationType.COUNT
161    ]
162)
163```
164 
165### Filter by Dimension
166 
167```python
168response = metrics_client.query_resource(
169    resource_uri=resource_uri,
170    metric_names=["Requests"],
171    timespan=timedelta(hours=1),
172    filter="ApiName eq 'GetBlob'"
173)
174```
175 
176### List Metric Definitions
177 
178```python
179definitions = metrics_client.list_metric_definitions(resource_uri)
180for definition in definitions:
181    print(f"{definition.name}: {definition.unit}")
182```
183 
184### List Metric Namespaces
185 
186```python
187namespaces = metrics_client.list_metric_namespaces(resource_uri)
188for ns in namespaces:
189    print(ns.fully_qualified_namespace)
190```
191 
192## Async Clients
193 
194```python
195from azure.monitor.query.aio import LogsQueryClient, MetricsQueryClient
196from azure.identity.aio import DefaultAzureCredential
197 
198async def query_logs():
199    credential = DefaultAzureCredential()
200    client = LogsQueryClient(credential)
201    
202    response = await client.query_workspace(
203        workspace_id=workspace_id,
204        query="AppRequests | take 10",
205        timespan=timedelta(hours=1)
206    )
207    
208    await client.close()
209    await credential.close()
210    return response
211```
212 
213## Common Kusto Queries
214 
215```kusto
216// Requests by status code
217AppRequests
218| summarize count() by ResultCode
219| order by count_ desc
220 
221// Exceptions over time
222AppExceptions
223| summarize count() by bin(TimeGenerated, 1h)
224 
225// Slow requests
226AppRequests
227| where DurationMs > 1000
228| project TimeGenerated, Name, DurationMs
229| order by DurationMs desc
230 
231// Top errors
232AppExceptions
233| summarize count() by ExceptionType
234| top 10 by count_
235```
236 
237## Client Types
238 
239| Client | Purpose |
240|--------|---------|
241| `LogsQueryClient` | Query Log Analytics workspaces |
242| `MetricsQueryClient` | Query Azure Monitor metrics |
243 
244## Best Practices
245 
2461. **Use timedelta** for relative time ranges
2472. **Handle partial results** for large queries
2483. **Use batch queries** when running multiple queries
2494. **Set appropriate granularity** for metrics to reduce data points
2505. **Convert to DataFrame** for easier data analysis
2516. **Use aggregations** to summarize metric data
2527. **Filter by dimensions** to narrow metric results
253