chore/msp/spec: tidy up custom alerts spec (#63050)

Follow-ups for #62885:

- Better docstrings for `mql`, `promql`
- `duration` -> `durationMinutes` to align with other config
- `alertpolicy.ResponseCodeMetric` -> `spec.CustomAlertCondition`: they're effectively the same type

Test plan: CI

dev/managedservicesplatform/internal/resource/alertpolicy/alertpolicy.go

@@ -105,13 +105,6 @@ type ResponseCodeMetric struct {
 	DurationMinutes *uint
 }
 
-// CustomAlert for alerting on a custom mql or promql query
-type CustomAlert struct {
-	Type            spec.CustomAlertQueryType
-	Query           string
-	DurationMinutes *uint
-}
-
 // DescriptionSuffix points to the service page and environment anchor expected to be
 // generated at https://handbook.sourcegraph.com/departments/engineering/teams/core-services/managed-services/platform/,
 // and should be added as a suffix to all alert descriptions.
@@ -150,7 +143,7 @@ type Config struct {
 	ThresholdAggregation *ThresholdAggregation
 	MetricAbsence        *MetricAbsence
 	ResponseCodeMetric   *ResponseCodeMetric
-	CustomAlert          *CustomAlert
+	CustomAlert          *spec.CustomAlertCondition
 }
 
 // makeDocsSubject prefixes the name with the service and environment for ease

dev/managedservicesplatform/spec/monitoring.go

@@ -141,13 +141,24 @@ type CustomAlert struct {
 }
 
 type CustomAlertCondition struct {
-	// Type is one of `MQL` or `PromQL`
+	// Type describes the format of the configured query, and is one of `mql` or
+	// `promql`:
+	//
+	// - MQL: GCP monitoring's custom 'Monitoring Query Language'. Good for more
+	//   complicated alerts.
+	// - PromQL: Prometheus's query language. Good for simple alerts that you
+	//   already know how to express in PromQL.
 	Type CustomAlertQueryType `yaml:"type"`
-	// Query is the MQL or PromQL query to execute
+	// Query is the MQL or PromQL query to execute, based on your configured 'type'.
+	// Refer to the following guides for more details on how to write queries
+	// for each type:
+	//
+	// - PromQL: https://cloud.google.com/monitoring/promql
+	// - MQL: https://cloud.google.com/monitoring/mql
 	Query string `yaml:"query"`
-	// Duration is the time in minutes the query must violate the threshold.
+	// DurationMinutes is the time in minutes the query must violate the threshold.
 	// to trigger the alert. Defaults to one minute.
-	Duration *uint `yaml:"duration,omitempty"`
+	DurationMinutes *uint `yaml:"durationMinutes,omitempty"`
 }
 
 func (c *CustomAlert) UnmarshalYAML(unmarshal func(interface{}) error) error {
@@ -190,9 +201,9 @@ func (c *CustomAlert) Validate() []error {
 		errs = append(errs, errors.New("customAlerts[].condition.query cannot be empty"))
 	}
 
-	if c.Condition.Duration != nil {
-		if *c.Condition.Duration > 1440 { // 24 hours
-			errs = append(errs, errors.New("customAlerts[].condition.duration must be less than 1440 minutes"))
+	if c.Condition.DurationMinutes != nil {
+		if *c.Condition.DurationMinutes > 1440 { // 24 hours
+			errs = append(errs, errors.New("customAlerts[].condition.durationMinutes must be less than 1440 minutes"))
 		}
 	}
 

dev/managedservicesplatform/stacks/monitoring/custom.go

@@ -29,11 +29,7 @@ func createCustomAlerts(
 			Description: config.Description,
 			Severity:    config.SeverityLevel,
 
-			CustomAlert: &alertpolicy.CustomAlert{
-				Type:            config.Condition.Type,
-				Query:           config.Condition.Query,
-				DurationMinutes: config.Condition.Duration,
-			},
+			CustomAlert: &config.Condition,
 
 			// Shared configuration
 			Service:              vars.Service,