From 7ef0a8e978164b4353f842f9dece0d3b943bdac4 Mon Sep 17 00:00:00 2001
From: Matt Carmody <matt.carmody@lightstep.com>
Date: Thu, 4 Jan 2024 13:11:52 -0500
Subject: [PATCH] docs: remove metric_condition, add composite alert examples
 (#197)

* remove metric_condition examples

* add composite alert example

* generate docs

* update the md.tmpl files, not the md files

* Update docs/resources/alert.md

Co-authored-by: Brian Lamb <5820125+lambcode@users.noreply.github.com>

* update the md.tmpl files, not the md files again

---------

Co-authored-by: Brian Lamb <5820125+lambcode@users.noreply.github.com>
---
 docs/resources/alert.md                      | 65 +++++++++++++++-
 docs/resources/metric_condition.md           | 79 --------------------
 templates/resources/alert.md.tmpl            | 65 +++++++++++++++-
 templates/resources/metric_condition.md.tmpl | 79 --------------------
 4 files changed, 126 insertions(+), 162 deletions(-)

diff --git a/docs/resources/alert.md b/docs/resources/alert.md
index 42219659..a61af19f 100644
--- a/docs/resources/alert.md
+++ b/docs/resources/alert.md
@@ -11,7 +11,7 @@ Provides a [Lightstep alert](https://api-docs.lightstep.com/reference/listalerts
 
 Visit [Lightstep's documentation](https://docs.lightstep.com/docs/about-alerts) for conceptual information about alerts and alert templates.
 
-## Example Usage
+## Example Usage (single alert)
 
 ```hcl
 resource "lightstep_alert" "beemo-requests" {
@@ -19,7 +19,7 @@ resource "lightstep_alert" "beemo-requests" {
   name         = "Frontend latency"
 
   expression {
-    is_multi   = true
+    is_multi   = false
     is_no_data = true
     operand    = "above"
     thresholds {
@@ -46,6 +46,67 @@ EOT
 }
 ```
 
+## Example Usage (composite alert)
+
+```hcl
+resource "lightstep_alert" "high_error_rate_with_sustained_traffic" {
+  project_name = var.project
+  name         = "Error rates are high for my operation with sustained traffic"
+  description  = <<EOF
+Fires when over 20% of requests have errors, but only when request count is above 75 over an hour window. This prevents firing when we have very low traffic and get a few error requests.
+EOF
+
+  label {
+    key   = "team"
+    value = "my_team"
+  }
+  composite_alert {
+    alert {
+      name  = "A"
+      title = "Span Error %"
+      expression {
+        operand = "above"
+        thresholds {
+          critical = 20
+        }
+      }
+      query {
+        hidden       = false
+        query_name   = "a"
+        query_string = "with\n\terrors = spans count | delta 1h | filter my_tag == my_value && error == true | group_by [], sum;\n\ttotal = spans count | delta 1h | filter my_tag == my_value | group_by [], sum;\njoin 100*errors / total, errors=0, total=0"
+        display      = "line"
+        hidden_queries = {
+          "a" = false
+        }
+      }
+    }
+
+    alert {
+      name  = "B"
+      title = "Span Count"
+      query {
+        hidden       = false
+        query_name   = "a"
+        query_string = "spans count | delta 1h | filter my_tag == my_value | group_by [], sum"
+        display      = "line"
+        hidden_queries = {
+          "a" = false
+        }
+      }
+      expression {
+        operand = "above"
+        thresholds {
+          critical = 75
+        }
+      }
+    }
+  }
+  alerting_rule {
+    id = lightstep_pagerduty_destination.my_destination.id
+  }
+}
+```
+
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
diff --git a/docs/resources/metric_condition.md b/docs/resources/metric_condition.md
index a9f1ec5f..65c9e83a 100644
--- a/docs/resources/metric_condition.md
+++ b/docs/resources/metric_condition.md
@@ -12,85 +12,6 @@ description: |-
 Provides a Lightstep Metric Condition. Use this resource to create and manage Lightstep Metric Conditions that can contain either
 metric queries or span queries.
 
-## Example Usage (metric query)
-
-```hcl
-resource "lightstep_metric_condition" "beemo-requests" {
-  project_name = var.project
-  name         = "Beemo Low Requests"
-
-  label {
-    key = "team"
-    value = "ontology"
-  }
-
-  label {
-    value = "custom-label"
-  }
-
-  expression {
-    is_multi   = true
-    is_no_data = true
-    operand    = "below"
-    thresholds {
-      warning  = 10.0
-      critical = 5.0
-    }
-  }
-
-  metric_query {
-    metric                              = "requests"
-    query_name                          = "a"
-    timeseries_operator                 = "delta"
-    timeseries_operator_input_window_ms = 30000
-    hidden                              = false
-    display                             = "line"
-
-    include_filters = [
-      {
-        key   = "kube_instance"
-        value = "3"
-      }
-    ]
-
-    group_by {
-      aggregation_method = "max"
-      keys               = ["key1", "key2"]
-    }
-  }
-```
-
-## Example Usage (span query)
-
-```hcl
-resource "lightstep_metric_condition" "beemo-requests" {
-  project_name = var.project
-  name         = "Frontend latency"
-
-  expression {
-    is_multi   = true
-    is_no_data = true
-    operand    = "above"
-    thresholds {
-      warning  = 5.0
-      critical = 10.0
-    }
-  }
-
-  metric_query {
-    query_name                          = "a"
-    hidden                              = false
-    display                             = "line"
-
-    spans {
-      query                    = "service IN (\"frontend\")"
-      operator                 = "latency"
-      operator_input_window_ms = 3600000
-      latency_percentiles      = [50]
-    }
-  }
-```
-
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
diff --git a/templates/resources/alert.md.tmpl b/templates/resources/alert.md.tmpl
index 9e0b8641..b312eb3b 100644
--- a/templates/resources/alert.md.tmpl
+++ b/templates/resources/alert.md.tmpl
@@ -11,7 +11,7 @@ Provides a [Lightstep alert](https://api-docs.lightstep.com/reference/listalerts
 
 Visit [Lightstep's documentation](https://docs.lightstep.com/docs/about-alerts) for conceptual information about alerts and alert templates.
 
-## Example Usage
+## Example Usage (single alert)
 
 ```hcl
 resource "lightstep_alert" "beemo-requests" {
@@ -19,7 +19,7 @@ resource "lightstep_alert" "beemo-requests" {
   name         = "Frontend latency"
 
   expression {
-    is_multi   = true
+    is_multi   = false
     is_no_data = true
     operand    = "above"
     thresholds {
@@ -46,4 +46,65 @@ EOT
 }
 ```
 
+## Example Usage (composite alert)
+
+```hcl
+resource "lightstep_alert" "high_error_rate_with_sustained_traffic" {
+  project_name = var.project
+  name         = "Error rates are high for my operation with sustained traffic"
+  description  = <<EOF
+Fires when over 20% of requests have errors, but only when request count is above 75 over an hour window. This prevents firing when we have very low traffic and get a few error requests.
+EOF
+
+  label {
+    key   = "team"
+    value = "my_team"
+  }
+  composite_alert {
+    alert {
+      name  = "A"
+      title = "Span Error %"
+      expression {
+        operand = "above"
+        thresholds {
+          critical = 20
+        }
+      }
+      query {
+        hidden       = false
+        query_name   = "a"
+        query_string = "with\n\terrors = spans count | delta 1h | filter my_tag == my_value && error == true | group_by [], sum;\n\ttotal = spans count | delta 1h | filter my_tag == my_value | group_by [], sum;\njoin 100*errors / total, errors=0, total=0"
+        display      = "line"
+        hidden_queries = {
+          "a" = false
+        }
+      }
+    }
+
+    alert {
+      name  = "B"
+      title = "Span Count"
+      query {
+        hidden       = false
+        query_name   = "a"
+        query_string = "spans count | delta 1h | filter my_tag == my_value | group_by [], sum"
+        display      = "line"
+        hidden_queries = {
+          "a" = false
+        }
+      }
+      expression {
+        operand = "above"
+        thresholds {
+          critical = 75
+        }
+      }
+    }
+  }
+  alerting_rule {
+    id = lightstep_pagerduty_destination.my_destination.id
+  }
+}
+```
+
 {{ .SchemaMarkdown | trimspace }}
diff --git a/templates/resources/metric_condition.md.tmpl b/templates/resources/metric_condition.md.tmpl
index 49a256b3..8cdcb5a1 100644
--- a/templates/resources/metric_condition.md.tmpl
+++ b/templates/resources/metric_condition.md.tmpl
@@ -12,83 +12,4 @@ description: |-
 Provides a Lightstep Metric Condition. Use this resource to create and manage Lightstep Metric Conditions that can contain either
 metric queries or span queries.
 
-## Example Usage (metric query)
-
-```hcl
-resource "lightstep_metric_condition" "beemo-requests" {
-  project_name = var.project
-  name         = "Beemo Low Requests"
-
-  label {
-    key = "team"
-    value = "ontology"
-  }
-
-  label {
-    value = "custom-label"
-  }
-
-  expression {
-    is_multi   = true
-    is_no_data = true
-    operand    = "below"
-    thresholds {
-      warning  = 10.0
-      critical = 5.0
-    }
-  }
-
-  metric_query {
-    metric                              = "requests"
-    query_name                          = "a"
-    timeseries_operator                 = "delta"
-    timeseries_operator_input_window_ms = 30000
-    hidden                              = false
-    display                             = "line"
-
-    include_filters = [
-      {
-        key   = "kube_instance"
-        value = "3"
-      }
-    ]
-
-    group_by {
-      aggregation_method = "max"
-      keys               = ["key1", "key2"]
-    }
-  }
-```
-
-## Example Usage (span query)
-
-```hcl
-resource "lightstep_metric_condition" "beemo-requests" {
-  project_name = var.project
-  name         = "Frontend latency"
-
-  expression {
-    is_multi   = true
-    is_no_data = true
-    operand    = "above"
-    thresholds {
-      warning  = 5.0
-      critical = 10.0
-    }
-  }
-
-  metric_query {
-    query_name                          = "a"
-    hidden                              = false
-    display                             = "line"
-
-    spans {
-      query                    = "service IN (\"frontend\")"
-      operator                 = "latency"
-      operator_input_window_ms = 3600000
-      latency_percentiles      = [50]
-    }
-  }
-```
-
 {{ .SchemaMarkdown | trimspace }}