From 464482d4ff5d846bd4c77dc02af57def6ff95e62 Mon Sep 17 00:00:00 2001 From: Ben Sully Date: Thu, 12 Sep 2024 10:31:01 +0100 Subject: [PATCH] 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. --- docs/resources/machine_learning_alert.md | 49 ++++--- docs/resources/machine_learning_holiday.md | 54 +++---- docs/resources/machine_learning_job.md | 136 +++++++++++++++--- .../machine_learning_outlier_detector.md | 83 ++++++----- .../{resource.tf => forecast_alert.tf} | 0 .../machinelearning/resource_alert_test.go | 4 +- .../resources/machine_learning_alert.md.tmpl | 31 ++++ .../machine_learning_holiday.md.tmpl | 31 ++++ .../resources/machine_learning_job.md.tmpl | 39 +++++ .../machine_learning_outlier_detector.md.tmpl | 31 ++++ 10 files changed, 361 insertions(+), 97 deletions(-) rename examples/resources/grafana_machine_learning_alert/{resource.tf => forecast_alert.tf} (100%) create mode 100644 templates/resources/machine_learning_alert.md.tmpl create mode 100644 templates/resources/machine_learning_holiday.md.tmpl create mode 100644 templates/resources/machine_learning_job.md.tmpl create mode 100644 templates/resources/machine_learning_outlier_detector.md.tmpl diff --git a/docs/resources/machine_learning_alert.md b/docs/resources/machine_learning_alert.md index 8972b5a26..0f8366680 100644 --- 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 - -### 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 index 3abe8f78f..fab2e9957 100644 --- 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 +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. - - -### 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 index 8eb186959..b9ad6c5f8 100644 --- 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 +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 index 6da145ebb..c8a96e960 100644 --- 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 - -### 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. - - -### 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. - -### 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/examples/resources/grafana_machine_learning_alert/resource.tf b/examples/resources/grafana_machine_learning_alert/forecast_alert.tf similarity index 100% rename from examples/resources/grafana_machine_learning_alert/resource.tf rename to examples/resources/grafana_machine_learning_alert/forecast_alert.tf diff --git a/internal/resources/machinelearning/resource_alert_test.go b/internal/resources/machinelearning/resource_alert_test.go index b7b12eb23..15c9cfa01 100644 --- 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\"", diff --git a/templates/resources/machine_learning_alert.md.tmpl b/templates/resources/machine_learning_alert.md.tmpl new file mode 100644 index 000000000..7aaa63b1d --- /dev/null +++ b/templates/resources/machine_learning_alert.md.tmpl @@ -0,0 +1,31 @@ +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}" +subcategory: "" +description: |- +{{ .Description | plainmarkdown | trimspace | prefixlines " " }} +--- + +# {{.Name}} ({{.Type}}) + +{{ .Description | trimspace }} + +## Example Usage + +### Forecast Alert + +This alert uses a forecast. + +{{ tffile "examples/resources/grafana_machine_learning_alert/forecast_alert.tf" }} + +### Outlier Alert + +This alert uses an outlier detector. + +{{ tffile "examples/resources/grafana_machine_learning_alert/outlier_alert.tf" }} + +## Import + +Import is supported using the following syntax: + +{{ codefile "shell" "examples/resources/grafana_machine_learning_alert/import.sh" }} diff --git a/templates/resources/machine_learning_holiday.md.tmpl b/templates/resources/machine_learning_holiday.md.tmpl new file mode 100644 index 000000000..585008d8f --- /dev/null +++ b/templates/resources/machine_learning_holiday.md.tmpl @@ -0,0 +1,31 @@ +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}" +subcategory: "" +description: |- +{{ .Description | plainmarkdown | trimspace | prefixlines " " }} +--- + +# {{.Name}} ({{.Type}}) + +{{ .Description | trimspace }} + +## Example Usage + +### iCal Holiday + +This holiday uses an iCal file to define the holidays. + +{{ tffile "examples/resources/grafana_machine_learning_holiday/ical_holiday.tf" }} + +### Custom Periods Holiday + +This holiday uses custom periods to define the holidays. + +{{ tffile "examples/resources/grafana_machine_learning_holiday/custom_periods_holiday.tf" }} + +## Import + +Import is supported using the following syntax: + +{{ codefile "shell" "examples/resources/grafana_machine_learning_holiday/import.sh" }} diff --git a/templates/resources/machine_learning_job.md.tmpl b/templates/resources/machine_learning_job.md.tmpl new file mode 100644 index 000000000..c0981260c --- /dev/null +++ b/templates/resources/machine_learning_job.md.tmpl @@ -0,0 +1,39 @@ +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}" +subcategory: "" +description: |- +{{ .Description | plainmarkdown | trimspace | prefixlines " " }} +--- + +# {{.Name}} ({{.Type}}) + +{{ .Description | trimspace }} + +## Example Usage + +### Basic Forecast + +This forecast uses a Prometheus datasource, where the source query is defined in the `expr` field of the `query_params` attribute. + +Other datasources are supported, but the structure `query_params` may differ. + +{{ tffile "examples/resources/grafana_machine_learning_job/job.tf" }} + +### Tuned Forecast + +This forecast has tuned hyperparameters to improve the accuracy of the model. + +{{ tffile "examples/resources/grafana_machine_learning_job/tuned_job.tf" }} + +### Forecast with Holidays + +This forecast has holidays which will be taken into account when training the model. + +{{ tffile "examples/resources/grafana_machine_learning_job/holidays_job.tf" }} + +## Import + +Import is supported using the following syntax: + +{{ codefile "shell" "examples/resources/grafana_machine_learning_job/import.sh" }} diff --git a/templates/resources/machine_learning_outlier_detector.md.tmpl b/templates/resources/machine_learning_outlier_detector.md.tmpl new file mode 100644 index 000000000..620506460 --- /dev/null +++ b/templates/resources/machine_learning_outlier_detector.md.tmpl @@ -0,0 +1,31 @@ +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}" +subcategory: "" +description: |- +{{ .Description | plainmarkdown | trimspace | prefixlines " " }} +--- + +# {{.Name}} ({{.Type}}) + +{{ .Description | trimspace }} + +## Example Usage + +### DBSCAN Outlier Detector + +This outlier detector uses the DBSCAN algorithm to detect outliers. + +{{ tffile "examples/resources/grafana_machine_learning_outlier_detector/dbscan.tf" }} + +### MAD Outlier Detector + +This outlier detector uses the Median Absolute Deviation (MAD) algorithm to detect outliers. + +{{ tffile "examples/resources/grafana_machine_learning_outlier_detector/mad.tf" }} + +## Import + +Import is supported using the following syntax: + +{{ codefile "shell" "examples/resources/grafana_machine_learning_outlier_detector/import.sh" }}