You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: sdk/monitor/azquery/README.md
+29-23Lines changed: 29 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,35 +1,37 @@
1
1
# Azure Monitor Query client module for Go
2
2
3
-
The Azure Monitor Query client library is used to execute read-only queries against [Azure Monitor][azure_monitor_overview]'s two data platforms:
3
+
The Azure Monitor Query client module is used to execute read-only queries against [Azure Monitor][azure_monitor_overview]'s two data platforms:
4
4
5
5
-[Logs][logs_overview] - Collects and organizes log and performance data from monitored resources. Data from different sources such as platform logs from Azure services, log and performance data from virtual machines agents, and usage and performance data from apps can be consolidated into a single [Azure Log Analytics workspace][log_analytics_workspace]. The various data types can be analyzed together using the [Kusto Query Language][kusto_query_language]. See the [Kusto to SQL cheat sheet][kusto_to_sql] for more information.
6
6
-[Metrics][metrics_overview] - Collects numeric data from monitored resources into a time series database. Metrics are numerical values that are collected at regular intervals and describe some aspect of a system at a particular time. Metrics are lightweight and capable of supporting near real-time scenarios, making them particularly useful for alerting and fast detection of issues.
* Go, version 1.18 or higher - [Install Go](https://go.dev/doc/install)
15
+
* Azure subscription - [Create a free account][azure_sub]
16
+
* To query logs, an Azure Log Analytics workspace ID - Create an [Azure Log Analytics workspace][log_analytics_workspace_create]
17
+
* To query metrics, the Resource URI of an Azure resource (Storage Account, Key Vault, CosmosDB, etc.) that you plan to monitor
18
+
19
+
### Install the packages
13
20
14
-
Install `azquery` and `azidentity` with `go get`:
15
-
```Bash
21
+
Install the `azquery` and `azidentity` modules with `go get`:
22
+
23
+
```bash
16
24
go get github.com/Azure/azure-sdk-for-go/sdk/monitor/azquery
17
25
go get github.com/Azure/azure-sdk-for-go/sdk/azidentity
18
26
```
19
-
[azidentity][azure_identity] is used for Azure Active Directory authentication during client construction.
20
-
21
-
### Prerequisites
22
27
23
-
* An [Azure subscription][azure_sub]
24
-
* A supported Go version (the Azure SDK supports the two most recent Go releases)
25
-
* For log queries, an [Azure Log Analytics workspace][log_analytics_workspace_create] ID.
26
-
* For metric queries, the Resource URI of any Azure resource (Storage Account, Key Vault, CosmosDB, etc).
28
+
The [azidentity][azure_identity] module is used for Azure Active Directory authentication during client construction.
27
29
28
30
### Authentication
29
31
30
-
This document demonstrates using [azidentity.NewDefaultAzureCredential][default_cred_ref] to authenticate. The client accepts any [azidentity][azure_identity] credential. See the [azidentity][azure_identity] documentation for more information about other credential types.
32
+
An authenticated client object is required to execute a query. The examples demonstrate using [azidentity.NewDefaultAzureCredential][default_cred_ref] to authenticate; however, the client accepts any [azidentity][azure_identity] credential. See the [azidentity][azure_identity] documentation for more information about other credential types.
31
33
32
-
The clients default to the Azure Public Cloud. See the [cloud][cloud_documentation]documentation for more information about other cloud configurations.
34
+
The clients default to the Azure public cloud. For other cloud configurations, see the [cloud][cloud_documentation]package documentation.
33
35
34
36
#### Create a logs client
35
37
@@ -43,7 +45,7 @@ Example [metrics client][example_metrics_client]
43
45
44
46
### Timespan
45
47
46
-
It's best practice to always query with a timespan (type `TimeInterval`) to prevent excessive queries of the entire logs or metrics data set. Log queries uses the ISO8601 Time Interval Standard. All time should be represented in UTC. If the timespan is included in both the Kusto query string and `Timespan` field, the timespan will be the intersection of the two values.
48
+
It's best practice to always query with a timespan (type `TimeInterval`) to prevent excessive queries of the entire logs or metrics data set. Log queries use the ISO8601 Time Interval Standard. All time should be represented in UTC. If the timespan is included in both the Kusto query string and `Timespan` field, the timespan is the intersection of the two values.
47
49
48
50
Use the `NewTimeInterval()` method for easy creation.
49
51
@@ -56,31 +58,31 @@ Each set of metric values is a time series with the following characteristics:
56
58
- A namespace that acts like a category for the metric
57
59
- A metric name
58
60
- The value itself
59
-
- Some metrics may have multiple dimensions as described in multi-dimensional metrics. Custom metrics can have up to 10 dimensions.
61
+
- Some metrics may have multiple dimensions as described in [multi-dimensional metrics][multi-metrics]. Custom metrics can have up to 10 dimensions.
60
62
61
63
### Logs query rate limits and throttling
62
64
63
65
The Log Analytics service applies throttling when the request rate is too high. Limits, such as the maximum number of rows returned, are also applied on the Kusto queries. For more information, see [Query API][service_limits].
64
66
65
67
If you're executing a batch logs query, a throttled request will return a `ErrorInfo` object. That object's `code` value will be `ThrottledError`.
66
68
67
-
### Advanced logs query
69
+
### Advanced logs queries
68
70
69
71
#### Query multiple workspaces
70
72
71
73
To run the same query against multiple Log Analytics workspaces, add the additional workspace ID strings to the `AdditionalWorkspaces` slice in the `Body` struct.
72
74
73
-
When multiple workspaces are included in the query, the logs in the result table are not grouped according to the workspace from which it was retrieved.
75
+
When multiple workspaces are included in the query, the logs in the result table are not grouped according to the workspace from which they were retrieved.
74
76
75
77
#### Increase wait time, include statistics, include render (visualization)
76
78
77
79
The `LogsQueryOptions` type is used for advanced logs options.
78
80
79
-
By default, your query will run for up to three minutes. To increase the default timeout, set `LogsQueryOptions.Wait` to the desired number of seconds. The maximum wait time the service will allow is ten minutes (600 seconds).
81
+
*By default, your query will run for up to three minutes. To increase the default timeout, set `LogsQueryOptions.Wait` to the desired number of seconds. The maximum wait time is 10 minutes (600 seconds).
80
82
81
-
To get logs query execution statistics, such as CPU and memory consumption, set `LogsQueryOptions.Statistics` to `true`.
83
+
*To get logs query execution statistics, such as CPU and memory consumption, set `LogsQueryOptions.Statistics` to `true`.
82
84
83
-
To get visualization data for logs queries, set `LogsQueryOptions.Visualization` to `true`.
85
+
*To get visualization data for logs queries, set `LogsQueryOptions.Visualization` to `true`.
84
86
85
87
```go
86
88
azquery.LogsClientQueryWorkspaceOptions{
@@ -98,9 +100,9 @@ To do the same with `QueryBatch`, set the values in the `BatchQueryRequest.Heade
98
100
99
101
Get started with our [examples][azquery_pkg_go_samples].
100
102
101
-
For the majority of log queries, use the `LogsClient.QueryWorkspace` method. The `LogsClient.QueryBatch` method should only be used in advanced scenerios.
103
+
*For the majority of log queries, use the `LogsClient.QueryWorkspace` method. Only use the `LogsClient.QueryBatch` method in advanced scenerios.
102
104
103
-
Use `MetricsClient.QueryResource` for metric queries.
105
+
*Use `MetricsClient.QueryResource` for metric queries.
0 commit comments