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 <[email protected]> * update the md.tmpl files, not the md files again --------- Co-authored-by: Brian Lamb <[email protected]>
lightstep · Jan 4, 2024 · 7ef0a8e · 7ef0a8e
1 parent ae8faf0
commit 7ef0a8e
Show file tree

Hide file tree

Showing 4 changed files with 126 additions and 162 deletions.
diff --git a/docs/resources/alert.md b/docs/resources/alert.md
@@ -11,15 +11,15 @@ 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" {
   project_name = var.project
   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
@@ -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
@@ -11,15 +11,15 @@ 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" {
   project_name = var.project
   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
@@ -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 }}