Monitor Query UX Study Feedback (Azure#19771)

* remove ColumnLookup

* rename workspaces to additionalworkspaces

* rename render to visualization

* timespan

* timespan struct

* added ISO8601TimeInterval type

* change batch names

* doc updates

* readme updates

* docs

* Update sdk/monitor/azquery/README.md

Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com>

* iso8601 timeinterval

* updated test recordings

* fix linter errors

* fix linting part 2

* charles suggestions

* more doc comments

* options update

* test updates

* joel feedback

* prep for release

* fix year to 2023

Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com>

Author: gracewilcox

sdk/monitor/azquery/CHANGELOG.md

@@ -1,14 +1,20 @@
 # Release History
 
-## 0.3.1 (Unreleased)
+## 0.4.0 (2023-01-12)
 
 ### Features Added
+* Added `TimeInterval` type with constructor to aid with timespan creation
+* Added `NewBatchQueryRequest` constructor to aid with logs batch requests
+* Added `LogsQueryOptions` model for easier setting of logs options
 
 ### Breaking Changes
-
-### Bugs Fixed
+* Changed type of `Body.Timespan`, `MetricsClientQueryResourceOptions.Timespan`, `Response.Timespan` from *string to *TimeInterval
+* Remove `ColumnIndexLookup` field from Table struct
+* Renamed `Body.Workspaces` to `Body.AdditionalWorkspaces`
+* Renamed `Results.Render` and `BatchResponse.Render` to `Results.Visualization` and `BatchResponse.Visualization`
 
 ### Other Changes
+* Doc and example updates
 
 ## 0.3.0 (2022-11-08)
 

sdk/monitor/azquery/README.md

@@ -68,6 +68,43 @@ directive:
       from: MetricNamespaces_List
       to: Metrics_ListNamespaces
 
+  # rename Body.Workspaces to Body.AdditionalWorkspaces
+  - from: swagger-document
+    where: $.definitions.queryBody.properties.workspaces
+    transform: $["x-ms-client-name"] = "AdditionalWorkspaces"
+  
+  # rename Render to Visualization
+  - from: swagger-document
+    where: $.definitions.queryResults.properties.render
+    transform: $["x-ms-client-name"] = "Visualization"
+  - from: swagger-document
+    where: $.definitions.batchQueryResults.properties.render
+    transform: $["x-ms-client-name"] = "Visualization"
+
+  # rename BatchQueryRequest.ID to BatchQueryRequest.CorrelationID
+  - from: swagger-document
+    where: $.definitions.batchQueryRequest.properties.id
+    transform: $["x-ms-client-name"] = "CorrelationID"
+  - from: swagger-document
+    where: $.definitions.batchQueryResponse.properties.id
+    transform: $["x-ms-client-name"] = "CorrelationID"
+
+  # rename BatchQueryRequest.Workspace to BatchQueryRequest.WorkspaceID
+  - from: swagger-document
+    where: $.definitions.batchQueryRequest.properties.workspace
+    transform: $["x-ms-client-name"] = "WorkspaceID"
+  
+  # rename Prefer to Options
+  - from: swagger-document
+    where: $.parameters.PreferHeaderParameter
+    transform: $["x-ms-client-name"] = "Options"
+  - from: models.go
+    where: $
+    transform: return $.replace(/Options \*string/g, "Options *LogsQueryOptions");
+  - from: logs_client.go
+    where: $
+    transform: return $.replace(/\*options\.Options/, "options.Options.String()");
+  
   # add default values for batch request path and method attributes
   - from: swagger-document
     where: $.definitions.batchQueryRequest.properties.path
@@ -90,6 +127,23 @@ directive:
     where: $
     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: $.definitions.queryBody.properties.workspaces
+    transform: $["description"] = "A list of workspaces to query in addition to the primary workspace."
+  - from: swagger-document
+    where: $.definitions.batchQueryRequest.properties.headers
+    transform: $["description"] = "Optional. Headers of the request. Can use prefer header to set server timeout, query statistics and visualization information. For more information, see https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/monitor/azquery#readme-increase-wait-time-include-statistics-include-render-visualization"
+  - from: swagger-document
+    where: $.definitions.batchQueryRequest.properties.workspace
+    transform: $["description"] = "Primary Workspace ID of the query"
+  - from: swagger-document
+    where: $.definitions.batchQueryRequest.properties.id
+    transform: $["description"] = "Unique ID corresponding to each request in the batch"
+  - from: swagger-document
+    where: $.parameters.workspaceId
+    transform: $["description"] = "Primary Workspace ID of the query. This is Workspace ID from the Properties blade in the Azure portal"
+
   # delete unused error models
   - from: models.go
     where: $
@@ -104,14 +158,6 @@ directive:
     where: $
     transform: return $.replace(/(?:\/\/.*\s)+func \(\w \*?(?:ErrorInfo|ErrorDetail)\).*\{\s(?:.+\s)+\}\s/g, "");
 
-  # delete generated table struct, using custom one instead
-  - from: models.go
-    where: $
-    transform: return $.replace(/(?:\/\/.*\s)+type (Table).+\{(?:\s.+\s)+\}\s/g, "");
-  - from: models_serde.go
-    where: $
-    transform: return $.replace(/(?:\/\/.*\s)+func \(\w \*?(\*Table)\).*\{\s(?:.+\s)+\}\s/g, "");
-
   # delete generated constructor and client
   - from: logs_client.go
     where: $
@@ -139,21 +185,37 @@ directive:
     where: $
     transform: return $.replace(/const host = "(.*?)"/, "");
 
+  # change Table.Rows from type [][]interface{} to type []Row
+  - from: models.go
+    where: $
+    transform: return $.replace(/Rows \[\]\[\]interface{}/, "Rows []Row");
+
   # change render and statistics type to []byte
   - from: models.go
     where: $
-    transform: return $.replace(/interface{}/g, "[]byte");
+    transform: return $.replace(/Statistics interface{}/g, "Statistics []byte");
+  - from: models.go
+    where: $
+    transform: return $.replace(/Visualization interface{}/g, "Visualization []byte");
   - from: models_serde.go
     where: $
     transform: return 
       $.replace(/err(.*)r\.Statistics\)/, "r.Statistics = val") 
   - from: models_serde.go
     where: $
-    transform: return $.replace(/err(.*)r\.Render\)/, "r.Render = val");
+    transform: return $.replace(/err(.*)r\.Visualization\)/, "r.Visualization = val");
   - from: models_serde.go
     where: $
     transform: return 
       $.replace(/err(.*)b\.Statistics\)/, "b.Statistics = val") 
   - from: models_serde.go
     where: $
-    transform: return $.replace(/err(.*)b\.Render\)/, "b.Render = val");
+    transform: return $.replace(/err(.*)b\.Visualization\)/, "b.Visualization = val");
+
+  # change type of timespan from *string to *TimeInterval
+  - from: models.go
+    where: $
+    transform: return $.replace(/Timespan \*string/g, "Timespan *TimeInterval");
+  - from: metrics_client.go
+    where: $
+    transform: return $.replace(/reqQP\.Set\(\"timespan\", \*options\.Timespan\)/g, "reqQP.Set(\"timespan\", string(*options.Timespan))");

sdk/monitor/azquery/autorest.md

@@ -13,6 +13,8 @@ import (
 	"errors"
 	"fmt"
 	"reflect"
+	"strings"
+	"time"
 
 	"github.com/Azure/azure-sdk-for-go/sdk/azcore"
 	"github.com/Azure/azure-sdk-for-go/sdk/azcore/cloud"
@@ -109,47 +111,83 @@ func (e *ErrorInfo) Error() string {
 // Row of data in a table, types of data used by service specified in LogsColumnType
 type Row []any
 
-// Table - Contains the columns and rows for one table in a query response.
-type Table struct {
-	// REQUIRED; The list of columns in this table.
-	Columns []*Column `json:"columns,omitempty"`
+// TimeInterval specifies the time range over which to query.
+// Use NewTimeInterval() for help formatting.
+// Follows the ISO8601 time interval standard with most common
+// format being startISOTime/endISOTime. ISO8601 durations also supported (ex "PT2H" for last two hours).
+// Use UTC for all times.
+type TimeInterval string
+
+// NewTimeInterval creates a TimeInterval for use in a query.
+// Use UTC for start and end times.
+func NewTimeInterval(start time.Time, end time.Time) TimeInterval {
+	return TimeInterval(start.Format(time.RFC3339) + "/" + end.Format(time.RFC3339))
+}
 
-	// REQUIRED; The name of the table.
-	Name *string `json:"name,omitempty"`
+// Values returns the interval's start and end times if it's in the format startISOTime/endISOTime, else it will return an error.
+func (i TimeInterval) Values() (time.Time, time.Time, error) {
+	// split into different start and end times
+	times := strings.Split(string(i), "/")
+	if len(times) != 2 {
+		return time.Time{}, time.Time{}, errors.New("time interval should be in format startISOTime/endISOTime")
+	}
+	start, err := time.Parse(time.RFC3339, times[0])
+	if err != nil {
+		return time.Time{}, time.Time{}, errors.New("error parsing start time")
+	}
+	end, err := time.Parse(time.RFC3339, times[1])
+	if err != nil {
+		return time.Time{}, time.Time{}, errors.New("error parsing end time")
+	}
+	// return times
+	return start, end, nil
+}
 
-	// REQUIRED; The resulting rows from this query.
-	Rows []Row `json:"rows,omitempty"`
+// LogsQueryOptions sets server timeout, query statistics and visualization information
+type LogsQueryOptions struct {
+	// Set Statistics to true to get logs query execution statistics,
+	// such as CPU and memory consumption. Defaults to false.
+	Statistics *bool
+
+	// Set Visualization to true to get visualization
+	// data for logs queries. Defaults to false.
+	Visualization *bool
+
+	// By default, the Azure Monitor Query service will run your
+	// query for up to three minutes. To increase the default timeout,
+	// set Wait to desired number of seconds.
+	// Max wait time the service will allow is ten minutes (600 seconds).
+	Wait *int
+}
 
-	// maps column name to index for easy lookup, helper for accessing Row data
-	ColumnIndexLookup map[string]int `json:"-"`
+// String implements the fmt.Stringer interface for type LogsQueryOptions.
+func (l LogsQueryOptions) String() string {
+	var options []string
+	if l.Statistics != nil && *l.Statistics {
+		options = append(options, "include-statistics=true")
+	}
+	if l.Visualization != nil && *l.Visualization {
+		options = append(options, "include-render=true")
+	}
+	if l.Wait != nil {
+		options = append(options, fmt.Sprintf("wait=%d", *l.Wait))
+	}
+	return strings.Join(options, ",")
 }
 
-// UnmarshalJSON implements the json.Unmarshaller interface for type Table.
-func (t *Table) UnmarshalJSON(data []byte) error {
-	var rawMsg map[string]json.RawMessage
-	if err := json.Unmarshal(data, &rawMsg); err != nil {
-		return fmt.Errorf("unmarshalling type %T: %v", t, err)
+// NewBatchQueryRequest creates a new BatchQueryRequest.
+func NewBatchQueryRequest(workspaceID string, query string, timespan TimeInterval, correlationID string, options LogsQueryOptions) BatchQueryRequest {
+	var optionsMap map[string]*string
+	if options.Statistics != nil || options.Visualization != nil || options.Wait != nil {
+		optionsMap = make(map[string]*string)
+		optionsString := options.String()
+		optionsMap["prefer"] = &optionsString
 	}
-	for key, val := range rawMsg {
-		var err error
-		switch key {
-		case "columns":
-			err = unpopulate(val, "Columns", &t.Columns)
-			delete(rawMsg, key)
-			t.ColumnIndexLookup = map[string]int{}
-			for i, v := range t.Columns {
-				t.ColumnIndexLookup[*v.Name] = i
-			}
-		case "name":
-			err = unpopulate(val, "Name", &t.Name)
-			delete(rawMsg, key)
-		case "rows":
-			err = unpopulate(val, "Rows", &t.Rows)
-			delete(rawMsg, key)
-		}
-		if err != nil {
-			return fmt.Errorf("unmarshalling type %T: %v", t, err)
-		}
+
+	return BatchQueryRequest{
+		Body:          &Body{Query: &query, Timespan: &timespan},
+		CorrelationID: &correlationID,
+		WorkspaceID:   &workspaceID,
+		Headers:       optionsMap,
 	}
-	return nil
 }