[azquery] Release prep and final updates

sdk/monitor/azquery/CHANGELOG.md

@@ -1,14 +1,13 @@
 # Release History
 
-## 0.4.1 (Unreleased)
-
-### Features Added
+## 1.0.0 (2023-02-08)
 
 ### Breaking Changes
-
-### Bugs Fixed
+* Removed `LogsQueryOptions.String()`
+* Fix casing on some metrics fields
 
 ### Other Changes
+* Doc and example updates
 
 ## 0.4.0 (2023-01-12)
 

sdk/monitor/azquery/TROUBLESHOOTING.md

@@ -114,20 +114,19 @@ The following code shows an example of setting the server timeout. By setting th
 
 ```go
 workspaceID := "<workspace_id>"
-prefer := "wait=600" // increases wait time to ten minutes
-cred, err := azidentity.NewDefaultAzureCredential(nil)
-if err != nil {
-    //TODO: handle error
-}
-client := azquery.NewLogsClient(cred, nil)
+options := &azquery.LogsClientQueryWorkspaceOptions{
+		Options: &azquery.LogsQueryOptions{
+			Wait:          to.Ptr(600), // increases wait time to ten minutes
+		},
+	}
 
-res, err := client.QueryWorkspace(context.Background(), 
+res, err := logsClient.QueryWorkspace(context.Background(), 
              workspaceID, 
              azquery.Body{Query: to.Ptr("AzureActivity
                     | summarize Count = count() by ResourceGroup
                     | top 10 by Count
                     | project ResourceGroup")}, 
-             &azquery.LogsClientQueryWorkspaceOptions{Prefer: &prefer})
+             options)
 if err != nil {
     //TODO: handle error
 }
@@ -144,9 +143,8 @@ sufficient permissions to query the workspace.
 {"error":{"code":"AuthorizationFailed","message":"The client '71d56230-5920-4856-8f33-c030b269d870' with object id '71d56230-5920-4856-8f33-c030b269d870' does not have authorization to perform action 'microsoft.insights/metrics/read' over scope '/subscriptions/faa080af-c1d8-40ad-9cce-e1a450ca5b57/resourceGroups/srnagar-azuresdkgroup/providers/Microsoft.CognitiveServices/accounts/srnagara-textanalytics/providers/microsoft.insights' or the scope is invalid. If access was recently granted, please refresh your credentials."}}
 ```
 
-1. Check that the application or user that is making the request has sufficient permissions:
-    * You can refer to this document to [manage access to workspaces][workspace_access]
-2. If the user or application is granted sufficient privileges to query the workspace, make sure you are
+1. Check that the application or user that is making the request has sufficient permissions.
+2. If the user or application is granted sufficient privileges to query the resource, make sure you are
    authenticating as that user/application. If you are authenticating using the
    [DefaultAzureCredential][default_azure_cred]
    then check the logs to verify that the credential used is the one you expected. To enable logging, see [enable
@@ -158,7 +156,7 @@ guide][azidentity_troubleshooting]
 ### Troubleshooting unsupported granularity for metrics query
 
 If you notice the following exception, this is due to an invalid time granularity in the metrics query request. Your
-query might look something like the following where `MetricsQueryOptions().setGranularity()` is set to an unsupported
+query might look something like the following where `MetricsClientQueryResourceOptions.Interval` is set to an unsupported
 duration.
 
 ```text
@@ -172,6 +170,6 @@ As documented in the error message, the supported granularity for metrics querie
 [azidentity_docs]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity
 [azidentity_troubleshooting]: https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/azidentity/TROUBLESHOOTING.md
 [default_azure_cred]: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/azidentity#defaultazurecredential
-[kusto]: https://docs.microsoft.com/azure/data-explorer/kusto/query
+[kusto]: https://learn.microsoft.com/azure/data-explorer/kusto/query
 [readme_authentication]: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/monitor/azquery#authentication
-[workspace_access]: https://docs.microsoft.com/azure/azure-monitor/logs/manage-access#manage-access-using-workspace-permissions
+[workspace_access]: https://learn.microsoft.com/azure/azure-monitor/logs/manage-access#manage-access-using-workspace-permissions

sdk/monitor/azquery/autorest.md

@@ -68,6 +68,26 @@ directive:
       from: MetricNamespaces_List
       to: Metrics_ListNamespaces
 
+  # rename some metrics fields
+  - from: swagger-document
+    where: $.definitions.Metric.properties.timeseries
+    transform: $["x-ms-client-name"] = "TimeSeries"
+  - from: swagger-document
+    where: $.definitions.TimeSeriesElement.properties.metadatavalues
+    transform: $["x-ms-client-name"] = "MetadataValues"
+  - from: swagger-document
+    where: $.definitions.Response.properties.resourceregion
+    transform: $["x-ms-client-name"] = "ResourceRegion"
+  - from: swagger-document
+    where: $.parameters.MetricNamespaceParameter
+    transform: $["x-ms-client-name"] = "MetricNamespace"
+  - from: swagger-document
+    where: $.parameters.MetricNamesParameter
+    transform: $["x-ms-client-name"] = "MetricNames"
+  - from: swagger-document
+    where: $.parameters.OrderByParameter
+    transform: $["x-ms-client-name"] = "OrderBy"
+
   # rename Body.Workspaces to Body.AdditionalWorkspaces
   - from: swagger-document
     where: $.definitions.queryBody.properties.workspaces
@@ -103,7 +123,7 @@ directive:
     transform: return $.replace(/Options \*string/g, "Options *LogsQueryOptions");
   - from: logs_client.go
     where: $
-    transform: return $.replace(/\*options\.Options/, "options.Options.String()");
+    transform: return $.replace(/\*options\.Options/, "options.Options.preferHeader()");
 
   # add default values for batch request path and method attributes
   - from: swagger-document
@@ -128,6 +148,18 @@ directive:
     transform: return $.replace(/type ResultType string/, "//ResultType - Reduces the set of data collected. The syntax allowed depends on the operation. See the operation's description for details.\ntype ResultType string");
 
   # update doc comments
+  - from: swagger-document
+    where: $.paths["/workspaces/{workspaceId}/query"].post
+    transform: $["description"] = "Executes an Analytics query for data."
+  - from: swagger-document
+    where: $.paths["/$batch"].post
+    transform: $["description"] = "Executes a batch of Analytics queries for data."
+  - from: swagger-document
+    where: $.definitions.queryResults.properties.tables
+    transform: $["description"] = "The results of the query in tabular format."
+  - from: swagger-document
+    where: $.definitions.batchQueryResults.properties.tables
+    transform: $["description"] = "The results of the query in tabular format."
   - from: swagger-document
     where: $.definitions.queryBody.properties.workspaces
     transform: $["description"] = "A list of workspaces to query in addition to the primary workspace."

sdk/monitor/azquery/custom_client.go

@@ -160,8 +160,9 @@ type LogsQueryOptions struct {
 	Wait *int
 }
 
-// String implements the fmt.Stringer interface for type LogsQueryOptions.
-func (l LogsQueryOptions) String() string {
+// preferHeader converts LogsQueryOptions from struct to properly formatted sting
+// to be used in the request Prefer Header
+func (l LogsQueryOptions) preferHeader() string {
 	var options []string
 	if l.Statistics != nil && *l.Statistics {
 		options = append(options, "include-statistics=true")
@@ -180,7 +181,7 @@ func NewBatchQueryRequest(workspaceID string, query string, timespan TimeInterva
 	var optionsMap map[string]*string
 	if options.Statistics != nil || options.Visualization != nil || options.Wait != nil {
 		optionsMap = make(map[string]*string)
-		optionsString := options.String()
+		optionsString := options.preferHeader()
 		optionsMap["prefer"] = &optionsString
 	}
 

sdk/monitor/azquery/example_test.go

@@ -56,8 +56,12 @@ func ExampleNewMetricsClient() {
 }
 
 func ExampleLogsClient_QueryWorkspace() {
-	// Basic QueryWorkspace example
+	// QueryWorkspace allows users to query log data.
 
+	// A workspace ID is required to query logs. To find the workspace ID:
+	// 1. If not already made, create a Log Analytics workspace (https://learn.microsoft.com/azure/azure-monitor/logs/quick-create-workspace).
+	// 2. Navigate to your workspace's page in the Azure portal.
+	// 3. From the **Overview** blade, copy the value of the ***Workspace ID*** property.
 	workspaceID := "g4d1e129-fb1e-4b0a-b234-250abc987ea65" // example Azure Log Analytics Workspace ID
 
 	res, err := logsClient.QueryWorkspace(
@@ -84,34 +88,45 @@ func ExampleLogsClient_QueryWorkspace() {
 }
 
 func ExampleLogsClient_QueryWorkspace_second() {
-	// Advanced QueryWorkspace Example
+	// `QueryWorkspace` also has more advanced options, including querying multiple workspaces
+	// and LogsQueryOptions (including statistics and visualization information and increasing default timeout).
 
+	// 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.
 	workspaceID1 := "g4d1e129-fb1e-4b0a-b234-250abc987ea65" // example Azure Log Analytics Workspace ID
 	workspaceID2 := "h4bc4471-2e8c-4b1c-8f47-12b9a4d5ac71"
+	additionalWorkspaces := []*string{to.Ptr(workspaceID2)}
+
+	// Advanced query options
+	// Setting Statistics to true returns stats information in Results.Statistics
+	// Setting Visualization to true returns visualization information in Results.Visualization
+	options := &azquery.LogsClientQueryWorkspaceOptions{
+		Options: &azquery.LogsQueryOptions{
+			Statistics:    to.Ptr(true),
+			Visualization: to.Ptr(true),
+			Wait:          to.Ptr(600),
+		},
+	}
 
 	res, err := logsClient.QueryWorkspace(
 		context.TODO(),
 		workspaceID1,
 		azquery.Body{
 			Query:                to.Ptr(query),
 			Timespan:             to.Ptr(azquery.NewTimeInterval(time.Date(2022, 12, 25, 0, 0, 0, 0, time.UTC), time.Date(2022, 12, 25, 12, 0, 0, 0, time.UTC))),
-			AdditionalWorkspaces: []*string{to.Ptr(workspaceID2)},
+			AdditionalWorkspaces: additionalWorkspaces,
 		},
-		to.Ptr(azquery.LogsClientQueryWorkspaceOptions{
-			Options: &azquery.LogsQueryOptions{
-				Statistics:    to.Ptr(true),
-				Visualization: to.Ptr(true),
-				Wait:          to.Ptr(600),
-			},
-		}))
+		options)
 	if err != nil {
 		//TODO: handle error
 	}
 	if res.Error != nil {
 		//TODO: handle partial error
 	}
 
-	// Example of converting table data into a slice of structs
+	// Example of converting table data into a slice of structs.
+	// Query results are returned in Table Rows and are of type any.
+	// Type assertion is required to access the underlying value of each index in a Row.
 	var QueryResults []queryResult
 	for _, table := range res.Tables {
 		QueryResults = make([]queryResult, len(table.Rows))
@@ -126,9 +141,19 @@ func ExampleLogsClient_QueryWorkspace_second() {
 	}
 
 	fmt.Println(QueryResults)
+
+	// Print out Statistics
+	fmt.Printf("Statistics: %s", string(res.Statistics))
+
+	// Print out Visualization information
+	fmt.Printf("Visualization: %s", string(res.Visualization))
+
 }
 
 func ExampleLogsClient_QueryBatch() {
+	// `QueryBatch` is an advanced method allowing users to execute multiple log queries in a single request.
+	// For help formatting a `BatchRequest`, please use the method `NewBatchQueryRequest`.
+
 	workspaceID := "g4d1e129-fb1e-4b0a-b234-250abc987ea65" // example Azure Log Analytics Workspace ID
 	timespan := azquery.NewTimeInterval(time.Date(2022, 12, 25, 0, 0, 0, 0, time.UTC), time.Date(2022, 12, 25, 12, 0, 0, 0, time.UTC))
 
@@ -143,6 +168,8 @@ func ExampleLogsClient_QueryBatch() {
 		//TODO: handle error
 	}
 
+	// `QueryBatch` can return results in any order, usually by time it takes each individual query to complete.
+	// Use the `CorrelationID` field to identify the correct response.
 	responses := res.BatchResponse.Responses
 	fmt.Println("ID's of successful responses:")
 	for _, response := range responses {
@@ -153,26 +180,44 @@ func ExampleLogsClient_QueryBatch() {
 }
 
 func ExampleMetricsClient_QueryResource() {
+	// QueryResource is used to query metrics on an Azure resource.
+	// For each requested metric, a set of aggregated values is returned inside the `TimeSeries` collection.
+
+	// resource ID is required to query metrics. To find the resource ID:
+	// 1. Navigate to your resource's page in the Azure portal.
+	// 2. From the **Overview** blade, select the **JSON View** link.
+	// 3. In the resulting JSON, copy the value of the `id` property.
+	resourceURI := "subscriptions/182c901a-129a-4f5d-86e4-afdsb294590a2/resourceGroups/test-log/providers/microsoft.insights/components/f1-bill/providers/microsoft.insights/metricdefinitions"
+
 	res, err := metricsClient.QueryResource(context.TODO(), resourceURI,
 		&azquery.MetricsClientQueryResourceOptions{
 			Timespan:        to.Ptr(azquery.NewTimeInterval(time.Date(2022, 12, 25, 0, 0, 0, 0, time.UTC), time.Date(2022, 12, 25, 12, 0, 0, 0, time.UTC))),
 			Interval:        to.Ptr("PT1M"),
-			Metricnames:     nil,
+			MetricNames:     nil,
 			Aggregation:     to.Ptr("Average,count"),
 			Top:             to.Ptr[int32](3),
-			Orderby:         to.Ptr("Average asc"),
+			OrderBy:         to.Ptr("Average asc"),
 			Filter:          to.Ptr("BlobType eq '*'"),
 			ResultType:      nil,
-			Metricnamespace: to.Ptr("Microsoft.Storage/storageAccounts/blobServices"),
+			MetricNamespace: to.Ptr("Microsoft.Storage/storageAccounts/blobServices"),
 		})
 	if err != nil {
 		//TODO: handle error
 	}
-	_ = res
+
+	// Print out metric name and the time stamps of each metric data point
+	for _, metric := range res.Value {
+		fmt.Println(*metric.Name.Value)
+		for _, timeSeriesElement := range metric.TimeSeries {
+			for _, metricValue := range timeSeriesElement.Data {
+				fmt.Println(metricValue.TimeStamp)
+			}
+		}
+	}
 }
 
 func ExampleMetricsClient_NewListDefinitionsPager() {
-	pager := metricsClient.NewListDefinitionsPager("subscriptions/182c901a-129a-4f5d-86e4-cc6b294590a2/resourceGroups/hyr-log/providers/microsoft.insights/components/f1-bill/providers/microsoft.insights/metricdefinitions", &azquery.MetricsClientListDefinitionsOptions{Metricnamespace: to.Ptr("microsoft.insights/components")})
+	pager := metricsClient.NewListDefinitionsPager(resourceURI, &azquery.MetricsClientListDefinitionsOptions{MetricNamespace: to.Ptr("microsoft.insights/components")})
 	for pager.More() {
 		nextResult, err := pager.NextPage(context.TODO())
 		if err != nil {
@@ -186,7 +231,7 @@ func ExampleMetricsClient_NewListDefinitionsPager() {
 }
 
 func ExampleMetricsClient_NewListNamespacesPager() {
-	pager := metricsClient.NewListNamespacesPager("subscriptions/182c901a-129a-4f5d-86e4-cc6b294590a2/resourceGroups/hyr-log/providers/microsoft.insights/components/f1-bill", &azquery.MetricsClientListNamespacesOptions{StartTime: to.Ptr("2020-08-31T15:53:00Z")})
+	pager := metricsClient.NewListNamespacesPager(resourceURI, &azquery.MetricsClientListNamespacesOptions{StartTime: to.Ptr("2020-08-31T15:53:00Z")})
 	for pager.More() {
 		nextResult, err := pager.NextPage(context.TODO())
 		if err != nil {

sdk/monitor/azquery/logs_client_test.go

@@ -260,10 +260,6 @@ func TestTimeInterval(t *testing.T) {
 	require.Error(t, err)
 }
 
-func TestLogsQueryOptions(t *testing.T) {
-
-}
-
 func TestLogConstants(t *testing.T) {
 	batchMethod := []azquery.BatchQueryRequestMethod{azquery.BatchQueryRequestMethodPOST}
 	batchMethodRes := azquery.PossibleBatchQueryRequestMethodValues()