docs: use custom templates for ML resource docs

Using custom templates, similar to SLO and Synthetic Monitoring, allows us to include multiple examples in the documentation of each resource, along with comments for each resource.
grafana · Sep 18, 2024 · 464482d · 464482d
1 parent 422b1f7
commit 464482d
Show file tree

Hide file tree

Showing 10 changed files with 361 additions and 97 deletions.
diff --git a/docs/resources/machine_learning_alert.md b/docs/resources/machine_learning_alert.md
@@ -12,6 +12,10 @@ description: |-
 
 ## Example Usage
 
+### Forecast Alert
+
+This alert uses a forecast.
+
 ```terraform
 resource "grafana_machine_learning_job" "test_alert_job" {
   name            = "Test Job"
@@ -32,28 +36,37 @@ resource "grafana_machine_learning_alert" "test_job_alert" {
 }
 ```
 
-<!-- schema generated by tfplugindocs -->
-## Schema
-
-### Required
-
-- `title` (String) The title of the alert.
+### Outlier Alert
 
-### Optional
+This alert uses an outlier detector.
 
-- `annotations` (Map of String) Annotations to add to the alert generated in Grafana.
-- `anomaly_condition` (String) The condition for when to consider a point as anomalous.
-- `for` (String) How long values must be anomalous before firing an alert.
-- `job_id` (String) The forecast this alert belongs to.
-- `labels` (Map of String) Labels to add to the alert generated in Grafana.
-- `no_data_state` (String) How the alert should be processed when no data is returned by the underlying series
-- `outlier_id` (String) The forecast this alert belongs to.
-- `threshold` (String) The threshold of points over the window that need to be anomalous to alert.
-- `window` (String) How much time to average values over
+```terraform
+resource "grafana_machine_learning_outlier_detector" "test_alert_outlier_detector" {
+  name = "Test Outlier"
 
-### Read-Only
+  metric          = "tf_test_alert_outlier"
+  datasource_type = "prometheus"
+  datasource_uid  = "AbCd12345"
+  query_params = {
+    expr = "grafanacloud_grafana_instance_active_user_count"
+  }
+  interval = 300
+
+  algorithm {
+    name        = "dbscan"
+    sensitivity = 0.5
+    config {
+      epsilon = 1.0
+    }
+  }
+}
 
-- `id` (String) The ID of the alert.
+resource "grafana_machine_learning_alert" "test_outlier_alert" {
+  outlier_id = grafana_machine_learning_outlier_detector.test_alert_outlier_detector.id
+  title      = "Test Alert"
+  window     = "1h"
+}
+```
 
 ## Import
 

diff --git a/docs/resources/machine_learning_holiday.md b/docs/resources/machine_learning_holiday.md
@@ -29,37 +29,43 @@ resource "grafana_machine_learning_job" "test_job" {
 }
 ```
 
+## Example Usage
 
+### iCal Holiday
 
-<!-- schema generated by tfplugindocs -->
-## Schema
+This holiday uses an iCal file to define the holidays.
 
-### Required
-
-- `name` (String) The name of the holiday.
-
-### Optional
-
-- `custom_periods` (Block List) A list of custom periods for the holiday. (see [below for nested schema](#nestedblock--custom_periods))
-- `description` (String) A description of the holiday.
-- `ical_timezone` (String) The timezone to use for events in the iCal file pointed to by ical_url.
-- `ical_url` (String) A URL to an iCal file containing all occurrences of the holiday.
-
-### Read-Only
-
-- `id` (String) The ID of the holiday.
-
-<a id="nestedblock--custom_periods"></a>
-### Nested Schema for `custom_periods`
+```terraform
+resource "grafana_machine_learning_holiday" "ical" {
+  name        = "My iCal holiday"
+  description = "My Holiday"
 
-Required:
+  ical_url      = "https://calendar.google.com/calendar/ical/en.uk%23holiday%40group.v.calendar.google.com/public/basic.ics"
+  ical_timezone = "Europe/London"
+}
+```
 
-- `end_time` (String)
-- `start_time` (String)
+### Custom Periods Holiday
 
-Optional:
+This holiday uses custom periods to define the holidays.
 
-- `name` (String) The name of the custom period.
+```terraform
+resource "grafana_machine_learning_holiday" "custom_periods" {
+  name        = "My custom periods holiday"
+  description = "My Holiday"
+
+  custom_periods {
+    name       = "First of January"
+    start_time = "2023-01-01T00:00:00Z"
+    end_time   = "2023-01-02T00:00:00Z"
+  }
+  custom_periods {
+    name       = "First of Feburary"
+    start_time = "2023-02-01T00:00:00Z"
+    end_time   = "2023-02-02T00:00:00Z"
+  }
+}
+```
 
 ## Import
 

diff --git a/docs/resources/machine_learning_job.md b/docs/resources/machine_learning_job.md
@@ -10,31 +10,133 @@ description: |-
 
 A job defines the queries and model parameters for a machine learning task.
 
+## Example Usage
 
+### Basic Forecast
 
-<!-- schema generated by tfplugindocs -->
-## Schema
+This forecast uses a Prometheus datasource, where the source query is defined in the `expr` field of the `query_params` attribute.
 
-### Required
+Other datasources are supported, but the structure `query_params` may differ.
 
-- `datasource_type` (String) The type of datasource being queried. Currently allowed values are prometheus, graphite, loki, postgres, and datadog.
-- `datasource_uid` (String) The uid of the datasource to query.
-- `metric` (String) The metric used to query the job results.
-- `name` (String) The name of the job.
-- `query_params` (Map of String) An object representing the query params to query Grafana with.
+```terraform
+resource "grafana_data_source" "foo" {
+  type                = "prometheus"
+  name                = "prometheus-ds-test"
+  uid                 = "prometheus-ds-test-uid"
+  url                 = "https://my-instance.com"
+  basic_auth_enabled  = true
+  basic_auth_username = "username"
 
-### Optional
+  json_data_encoded = jsonencode({
+    httpMethod        = "POST"
+    prometheusType    = "Mimir"
+    prometheusVersion = "2.4.0"
+  })
 
-- `custom_labels` (Map of String) An object representing the custom labels added on the forecast.
-- `description` (String) A description of the job.
-- `holidays` (List of String) A list of holiday IDs or names to take into account when training the model.
-- `hyper_params` (Map of String) The hyperparameters used to fine tune the algorithm. See https://grafana.com/docs/grafana-cloud/machine-learning/models/ for the full list of available hyperparameters. Defaults to `map[]`.
-- `interval` (Number) The data interval in seconds to train the data on. Defaults to `300`.
-- `training_window` (Number) The data interval in seconds to train the data on. Defaults to `7776000`.
+  secure_json_data_encoded = jsonencode({
+    basicAuthPassword = "password"
+  })
+}
 
-### Read-Only
+resource "grafana_machine_learning_job" "test_job" {
+  name            = "Test Job"
+  metric          = "tf_test_job"
+  datasource_type = "prometheus"
+  datasource_uid  = grafana_data_source.foo.uid
+  query_params = {
+    expr = "grafanacloud_grafana_instance_active_user_count"
+  }
+}
+```
+
+### Tuned Forecast
+
+This forecast has tuned hyperparameters to improve the accuracy of the model.
+
+```terraform
+resource "grafana_data_source" "foo" {
+  type                = "prometheus"
+  name                = "prometheus-ds-test"
+  uid                 = "prometheus-ds-test-uid"
+  url                 = "https://my-instance.com"
+  basic_auth_enabled  = true
+  basic_auth_username = "username"
+
+  json_data_encoded = jsonencode({
+    httpMethod        = "POST"
+    prometheusType    = "Mimir"
+    prometheusVersion = "2.4.0"
+  })
+
+  secure_json_data_encoded = jsonencode({
+    basicAuthPassword = "password"
+  })
+}
+
+resource "grafana_machine_learning_job" "test_job" {
+  name            = "Test Job"
+  metric          = "tf_test_job"
+  datasource_type = "prometheus"
+  datasource_uid  = grafana_data_source.foo.uid
+  query_params = {
+    expr = "grafanacloud_grafana_instance_active_user_count"
+  }
+  hyper_params = {
+    daily_seasonality  = 15
+    weekly_seasonality = 10
+  }
+  custom_labels = {
+    example_label = "example_value"
+  }
+}
+```
 
-- `id` (String) The ID of the job.
+### Forecast with Holidays
+
+This forecast has holidays which will be taken into account when training the model.
+
+```terraform
+resource "grafana_data_source" "foo" {
+  type                = "prometheus"
+  name                = "prometheus-ds-test"
+  uid                 = "prometheus-ds-test-uid"
+  url                 = "https://my-instance.com"
+  basic_auth_enabled  = true
+  basic_auth_username = "username"
+
+  json_data_encoded = jsonencode({
+    httpMethod        = "POST"
+    prometheusType    = "Mimir"
+    prometheusVersion = "2.4.0"
+  })
+
+  secure_json_data_encoded = jsonencode({
+    basicAuthPassword = "password"
+  })
+}
+
+resource "grafana_machine_learning_holiday" "test_holiday" {
+  name = "Test Holiday"
+  custom_periods {
+    name       = "First of January"
+    start_time = "2023-01-01T00:00:00Z"
+    end_time   = "2023-01-02T00:00:00Z"
+  }
+}
+
+resource "grafana_machine_learning_job" "test_job" {
+  name            = "Test Job"
+  metric          = "tf_test_job"
+  datasource_type = "prometheus"
+  datasource_uid  = grafana_data_source.foo.uid
+  query_params = {
+    expr = "grafanacloud_grafana_instance_active_user_count"
+  }
+  holidays = [
+    grafana_machine_learning_holiday.test_holiday.id
+  ]
+}
+```
 
 ## Import
 

diff --git a/docs/resources/machine_learning_outlier_detector.md b/docs/resources/machine_learning_outlier_detector.md
@@ -16,47 +16,58 @@ The normal band is configured by choice of algorithm, its sensitivity and other
 
 Visit https://grafana.com/docs/grafana-cloud/machine-learning/outlier-detection/ for more details.
 
+## Example Usage
+
+### DBSCAN Outlier Detector
+
+This outlier detector uses the DBSCAN algorithm to detect outliers.
+
+```terraform
+resource "grafana_machine_learning_outlier_detector" "my_dbscan_outlier_detector" {
+  name        = "My DBSCAN outlier detector"
+  description = "My DBSCAN Outlier Detector"
+
+  metric          = "tf_test_dbscan_job"
+  datasource_type = "prometheus"
+  datasource_uid  = "AbCd12345"
+  query_params = {
+    expr = "grafanacloud_grafana_instance_active_user_count"
+  }
+  interval = 300
+
+  algorithm {
+    name        = "dbscan"
+    sensitivity = 0.5
+    config {
+      epsilon = 1.0
+    }
+  }
+}
+```
 
+### MAD Outlier Detector
 
-<!-- schema generated by tfplugindocs -->
-## Schema
-
-### Required
-
-- `algorithm` (Block Set, Min: 1, Max: 1) The algorithm to use and its configuration. See https://grafana.com/docs/grafana-cloud/machine-learning/outlier-detection/ for details. (see [below for nested schema](#nestedblock--algorithm))
-- `datasource_type` (String) The type of datasource being queried. Currently allowed values are prometheus, graphite, loki, postgres, and datadog.
-- `datasource_uid` (String) The uid of the datasource to query.
-- `metric` (String) The metric used to query the outlier detector results.
-- `name` (String) The name of the outlier detector.
-- `query_params` (Map of String) An object representing the query params to query Grafana with.
-
-### Optional
-
-- `description` (String) A description of the outlier detector.
-- `interval` (Number) The data interval in seconds to monitor. Defaults to `300`.
-
-### Read-Only
-
-- `id` (String) The ID of the outlier detector.
-
-<a id="nestedblock--algorithm"></a>
-### Nested Schema for `algorithm`
-
-Required:
-
-- `name` (String) The name of the algorithm to use ('mad' or 'dbscan').
-- `sensitivity` (Number) Specify the sensitivity of the detector (in range [0,1]).
-
-Optional:
-
-- `config` (Block Set, Max: 1) For DBSCAN only, specify the configuration map (see [below for nested schema](#nestedblock--algorithm--config))
+This outlier detector uses the Median Absolute Deviation (MAD) algorithm to detect outliers.
 
-<a id="nestedblock--algorithm--config"></a>
-### Nested Schema for `algorithm.config`
+```terraform
+resource "grafana_machine_learning_outlier_detector" "my_mad_outlier_detector" {
+  name        = "My MAD outlier detector"
+  description = "My MAD Outlier Detector"
 
-Required:
+  metric          = "tf_test_mad_job"
+  datasource_type = "prometheus"
+  datasource_uid  = "AbCd12345"
+  query_params = {
+    expr = "grafanacloud_grafana_instance_active_user_count"
+  }
+  interval = 300
 
-- `epsilon` (Number) Specify the epsilon parameter (positive float)
+  algorithm {
+    name        = "mad"
+    sensitivity = 0.7
+  }
+}
+```
 
 ## Import
 

diff --git a/...rafana_machine_learning_alert/resource.tf → ..._machine_learning_alert/forecast_alert.tf b/...rafana_machine_learning_alert/resource.tf → ..._machine_learning_alert/forecast_alert.tf
diff --git a/internal/resources/machinelearning/resource_alert_test.go b/internal/resources/machinelearning/resource_alert_test.go
@@ -30,7 +30,7 @@ func TestAccResourceJobAlert(t *testing.T) {
 		),
 		Steps: []resource.TestStep{
 			{
-				Config: testutils.TestAccExampleWithReplace(t, "resources/grafana_machine_learning_alert/resource.tf", map[string]string{
+				Config: testutils.TestAccExampleWithReplace(t, "resources/grafana_machine_learning_alert/forecast_alert.tf", map[string]string{
 					"Test Job":   randomJobName,
 					"Test Alert": randomAlertName,
 				}),
@@ -46,7 +46,7 @@ func TestAccResourceJobAlert(t *testing.T) {
 			},
 			// Update the alert with a new anomaly condition.
 			{
-				Config: testutils.TestAccExampleWithReplace(t, "resources/grafana_machine_learning_alert/resource.tf", map[string]string{
+				Config: testutils.TestAccExampleWithReplace(t, "resources/grafana_machine_learning_alert/forecast_alert.tf", map[string]string{
 					"Test Job":   randomJobName,
 					"Test Alert": randomAlertName,
 					"\"any\"":    "\"low\"",