Skip to content

Commit 75b4544

Browse files
rakshith91rakshith91
authored
Troubleshooting guide for query (Azure#23737)
* Troubleshooting guide for query * missing import * comments
1 parent 8349a26 commit 75b4544

File tree

2 files changed

+216
-1
lines changed

2 files changed

+216
-1
lines changed

‎sdk/monitor/azure-monitor-query/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,8 +119,9 @@ For example:
119119
import os
120120
import pandas as pd
121121
from datetime import datetime, timezone
122-
from azure.monitor.query import LogsQueryClient
122+
from azure.monitor.query import LogsQueryClient, LogsQueryStatus
123123
from azure.identity import DefaultAzureCredential
124+
from azure.core.exceptions import HttpResponseError
124125

125126
credential = DefaultAzureCredential()
126127
client = LogsQueryClient(credential)

‎sdk/monitor/azure-monitor-query/TROUBLESHOOTING.md‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
# Troubleshooting Azure Monitor Query client library issues
2+
3+
This troubleshooting guide contains instructions to diagnose frequently encountered issues while using the Azure Monitor Query client library for Python.
4+
5+
## Table of contents
6+
7+
* [General Troubleshooting](#general-troubleshooting)
8+
* [Enable client logging](#enable-client-logging)
9+
* [Troubleshooting authentication issues with logs and metrics query requests](#authentication-errors)
10+
* [Troubleshooting running async APIs](#errors-with-running-async-apis)
11+
* [Troubleshooting Logs Query](#troubleshooting-logs-query)
12+
* [Troubleshooting insufficient access error](#troubleshooting-insufficient-access-error-for-logs-query)
13+
* [Troubleshooting invalid Kusto query](#troubleshooting-invalid-kusto-query)
14+
* [Troubleshooting empty log query results](#troubleshooting-empty-log-query-results)
15+
* [Troubleshooting server timeouts when executing logs query request](#troubleshooting-server-timeouts-when-executing-logs-query-request)
16+
* [Troubleshooting partially successful logs query requests](#troubleshooting-partially-successful-logs-query-requests)
17+
* [Troubleshooting Metrics Query](#troubleshooting-metrics-query)
18+
* [Troubleshooting insufficient access error](#troubleshooting-insufficient-access-error-for-metrics-query)
19+
* [Troubleshooting unsupported granularity for metrics query](#troubleshooting-unsupported-granularity-for-metrics-query)
20+
* [Additional azure-core configurations](#additional-azure-core-configurations)
21+
22+
## General Troubleshooting
23+
24+
Monitor query raises exceptions described in [`azure-core`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md)
25+
26+
### Enable client logging
27+
28+
To troubleshoot issues with Azure Monitor query library, it is important to first enable logging to monitor the behavior of the application. The errors and warnings in the logs generally provide useful insights into what went wrong and sometimes include corrective actions to fix issues.
29+
30+
This library uses the standard [logging](https://docs.python.org/3/library/logging.html) library for logging. Basic information about HTTP sessions, such as URLs and headers, is logged at the INFO level.
31+
Detailed DEBUG level logging, including request/response bodies and unredacted headers, can be enabled on a client with the logging_enable argument:
32+
33+
```python
34+
import logging
35+
from azure.monitor.query import LogsQueryClient
36+
37+
# Create a logger for the 'azure.monitor.query' SDK
38+
logger = logging.getLogger('azure.monitor.query')
39+
logger.setLevel(logging.DEBUG)
40+
41+
# Configure a console output
42+
handler = logging.StreamHandler(stream=sys.stdout)
43+
logger.addHandler(handler)
44+
45+
client = LogsQueryClient(credential, logging_enable=True)
46+
```
47+
48+
Similarly, logging_enable can enable detailed logging for a single operation, even when it isn't enabled for the client:
49+
50+
```python
51+
client.query_workspace(logging_enable=True)
52+
```
53+
54+
### Authentication errors
55+
56+
Azure Monitor Query supports Azure Active Directory authentication. Both LogsQueryClient and
57+
MetricsQueryClient have methods to set the `credential`. To provide a valid credential, you can use
58+
`azure-identity` dependency. For more details on getting started, refer to
59+
the [README](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/monitor/azure-monitor-query#create-the-client)
60+
of Azure Monitor Query library. You can also refer to
61+
the [Azure Identity documentation](https://docs.microsoft.com/python/api/overview/azure/identity-readme)
62+
for more details on the various types of credential supported in `azure-identity`.
63+
64+
For more help on troubleshooting authentication errors please see the Azure Identity client library [troubleshooting guide](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity/TROUBLESHOOTING.md).
65+
66+
### Errors with running async APIs
67+
68+
The async transport is designed to be opt-in. [AioHttp](https://pypi.org/project/aiohttp/) is one of the supported implementations of async transport. It is not installed by default. You need to install it separately as follows:
69+
70+
```
71+
pip install aiohttp
72+
```
73+
74+
## Troubleshooting Logs Query
75+
76+
### Troubleshooting insufficient access error for logs query
77+
78+
If you get an HTTP error with status code 403 (Forbidden), it means that the provided credentials does not have
79+
sufficient permissions to query the workspace.
80+
```text
81+
"{"error":{"message":"The provided credentials have insufficient access to perform the requested operation","code":"InsufficientAccessError","correlationId":""}}"
82+
```
83+
84+
1. Check that the application or user that is making the request has sufficient permissions:
85+
* You can refer to this document to [manage access to workspaces](https://docs.microsoft.com/azure/azure-monitor/logs/manage-access#manage-access-using-workspace-permissions)
86+
2. If the user or application is granted sufficient privileges to query the workspace, make sure you are
87+
authenticating as that user/application. If you are authenticating using the
88+
[DefaultAzureCredential](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#defaultazurecredential)
89+
then check the logs to verify that the credential used is the one you expected. To enable logging, see [enable
90+
client logging](#enable-client-logging) section above.
91+
92+
For more help on troubleshooting authentication errors please see the Azure Identity client library [troubleshooting guide](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity/TROUBLESHOOTING.md).
93+
94+
### Troubleshooting invalid Kusto query
95+
96+
If you get an HTTP error with status code 400 (Bad Request), you may have an error in your Kusto query and you'll
97+
see an error message similar to the one below.
98+
99+
```text
100+
(BadArgumentError) The request had some invalid properties
101+
Code: BadArgumentError
102+
Message: The request had some invalid properties
103+
Inner error: {
104+
"code": "SemanticError",
105+
"message": "A semantic error occurred.",
106+
"innererror": {
107+
"code": "SEM0100",
108+
"message": "'take' operator: Failed to resolve table or column expression named 'Appquests'"
109+
}
110+
}
111+
```
112+
113+
The error message in the innererror may include the where the Kusto query has an error. You may also refer to the [Kusto Query Language](https://docs.microsoft.com/azure/data-explorer/kusto/query) reference docs to learn more about querying logs using KQL.
114+
115+
### Troubleshooting empty log query results
116+
117+
If your Kusto query returns empty no logs, please validate the following:
118+
119+
- You have the right workspace ID
120+
- You are setting the correct time interval for the query. Try expanding the time interval for your query to see if that
121+
returns any results.
122+
- If your Kusto query also has a time interval, the query is evaluated for the intersection of the time interval in the
123+
query string and the time interval set in the `timespan` param provided the query API. The intersection of
124+
these time intervals may not have any logs. To avoid any confusion, it's recommended to remove any time interval in
125+
the Kusto query string and use `timespan` explicitly. Please note that the `timespan` param can be a timedelta,
126+
a timedelta and a start datetime, or a start datetime/end datetime.
127+
128+
### Troubleshooting server timeouts when executing logs query request
129+
130+
Some complex Kusto queries can take a long time to complete and such queries are aborted by the
131+
service if they run for more than 3 minutes. For such scenarios, the query APIs on `LogsQueryClient`, provide options to
132+
configure the timeout on the server. The server timeout can be extended up to 10 minutes.
133+
134+
You may see an error as follows:
135+
136+
```text
137+
Code: GatewayTimeout
138+
Message: Gateway timeout
139+
Inner error: {
140+
"code": "GatewayTimeout",
141+
"message": "Unable to unzip response"
142+
}
143+
```
144+
145+
The following code shows a sample on how to set the server timeout to 10 minutes. Note that by setting this server
146+
timeout, the Azure Monitor Query library will automatically also extend the client timeout to wait for 10 minutes for
147+
the server to respond. You don't need to configure your HTTP client to extend the response timeout as shown in the
148+
previous section.
149+
150+
```python
151+
from azure.monitor.query import LogsQueryClient
152+
from azure.identity import DefaultAzureCredential
153+
154+
credential = DefaultAzureCredential()
155+
156+
client = LogsQueryClient(credential)
157+
158+
client.query_workspace(
159+
"{workspaceId}",
160+
"{kusto-query-string}",
161+
timespan="{timespan}",
162+
server_timeout=600)
163+
```
164+
165+
### Troubleshooting partially successful logs query requests
166+
167+
By default, if the execution of a Kusto query resulted in a partially successful response, the Azure Monitor Query
168+
client library will throw an exception to indicate to the user that the query was not fully successful. The data and
169+
the error can be accessed using the `partial_data` and `partial_error` fields.
170+
171+
```python
172+
response = client.query_workspace("{workspaceId}", "{kusto-query-string}", timespan="{timespan}")
173+
174+
data = response.partial_data
175+
error = response.partial_error
176+
```
177+
178+
## Troubleshooting Metrics Query
179+
180+
### Troubleshooting insufficient access error for metrics query
181+
182+
If you get an HTTP error with status code 403 (Forbidden), it means that the provided credentials does not have
183+
sufficient permissions to query the workspace.
184+
```text
185+
"{"error":{"message":"The provided credentials have insufficient access to perform the requested operation","code":"InsufficientAccessError","correlationId":""}}"
186+
```
187+
188+
1. Check that the application or user that is making the request has sufficient permissions:
189+
* You can refer to this document to [manage access to workspaces](https://docs.microsoft.com/azure/azure-monitor/logs/manage-access#manage-access-using-workspace-permissions)
190+
2. If the user or application is granted sufficient privileges to query the workspace, make sure you are
191+
authenticating as that user/application. If you are authenticating using the
192+
[DefaultAzureCredential](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#defaultazurecredential)
193+
then check the logs to verify that the credential used is the one you expected. To enable logging, see [enable
194+
client logging](#enable-client-logging) section above.
195+
196+
For more help on troubleshooting authentication errors please see the Azure Identity client library [troubleshooting guide](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity/TROUBLESHOOTING.md).
197+
198+
### Troubleshooting unsupported granularity for metrics query
199+
200+
If you notice the following exception, this is due to an invalid time granularity in the metrics query request. Your
201+
query might have set the `granularity` keyword argument to an unsupported duration.
202+
203+
```text
204+
"{"code":"BadRequest","message":"Invalid time grain duration: PT10M, supported ones are: 00:01:00,00:05:00,00:15:00,00:30:00,01:00:00,06:00:00,12:00:00,1.00:00:00"}"
205+
```
206+
207+
As documented in the error message, the supported granularity for metrics queries are 1 minute, 5 minutes, 15 minutes,
208+
30 minutes, 1 hour, 6 hours, 12 hours and 1 day.
209+
210+
211+
## Additional azure-core configurations
212+
213+
When calling the methods, some properties including `retry_mode`, `timeout`, `connection_verify` can be configured by passing in as keyword arguments. See
214+
[configurations](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md#configurations) for list of all such properties.

0 commit comments

Comments
 (0)