Document some stuff better

src/crd/service_alert.rs

@@ -1,5 +1,5 @@
-use std::collections::HashMap;
 use std::hash::Hash;
+use std::{collections::HashMap, fmt::Display};
 
 use kube::CustomResource;
 use schemars::JsonSchema;
@@ -87,6 +87,16 @@ pub enum Operation {
     MoreThan,
 }
 
+impl Display for Operation {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Operation::EqualTo => write!(f, "=="),
+            Operation::LessThan => write!(f, "<"),
+            Operation::MoreThan => write!(f, ">"),
+        }
+    }
+}
+
 #[derive(Debug, Serialize, Deserialize, Clone, JsonSchema, Eq, PartialEq, Hash)]
 #[serde(rename_all = "camelCase")]
 pub enum Severity {

src/prometheus/alert.rs

@@ -105,54 +105,3 @@ impl From<&HashMap<String, String>> for PrometheusSeverity {
         }
     }
 }
-
-#[cfg(test)]
-mod test {
-    use color_eyre::Result;
-    use pretty_assertions::assert_eq;
-
-    use super::*;
-
-    const SERIALIZED_PROM_ALERT: &str = r#"
-groups:
-- name: example
-  rules:
-  - alert: HighRequestLatency
-    expr: job:request_latency_seconds:mean5m{job="myjob"} > 0.5
-    for: 10m
-    labels:
-      severity: page
-      source: cloud
-      owner: service
-    annotations:
-      summary: High request latency
-      description: Request latency over 9000"#;
-
-    #[test]
-    fn test_serialisation_happy_path() -> Result<()> {
-        let rust_repr = PromAlerts {
-            groups: vec![AlertGroup {
-                name: "example".into(),
-                rules: vec![AlertRules {
-                    alert: "HighRequestLatency".into(),
-                    expr: r#"job:request_latency_seconds:mean5m{job="myjob"} > 0.5"#.into(),
-                    for_: "10m".into(),
-                    labels: Labels {
-                        severity: PrometheusSeverity::Page,
-                        source: "cloud".into(),
-                        owner: "service".into(),
-                    },
-                    annotations: Annotations {
-                        summary: "High request latency".into(),
-                        description: "Request latency over 9000".into(),
-                    },
-                }],
-            }],
-        };
-
-        let yaml_repr: PromAlerts = serde_yaml::from_str(SERIALIZED_PROM_ALERT)?;
-        assert_eq!(yaml_repr, rust_repr);
-
-        Ok(())
-    }
-}

src/prometheus/mod.rs

@@ -7,3 +7,6 @@
 
 pub mod alert;
 pub mod replica_alerts;
+
+#[cfg(test)]
+mod tests;

src/prometheus/replica_alerts.rs

@@ -2,6 +2,9 @@ use crate::crd::{AlertConfig, Operation, ServiceAlertSpec};
 
 use super::alert::{AlertGroup, AlertRules, Annotations, Labels, PrometheusSeverity};
 
+/// Generates an [`AlertGroup`] for a list of defined replica alerts. Caller is
+/// responsible for only passing in a slice of alerts that are actually replica
+/// alerts!
 pub fn replica_count_rules(alert_configs: &[AlertConfig], spec: &ServiceAlertSpec) -> AlertGroup {
     // Prometheus Alert Rules in a single file must be uniquely named, but we
     // can't generate a *random* unique identifier, since that would break the
@@ -40,26 +43,28 @@ pub fn replica_count_rules(alert_configs: &[AlertConfig], spec: &ServiceAlertSpe
 //     aggr: String,
 // }
 
+/// Returns a [`String`] containing the PromQL expression for a given
+/// [`AlertConfig`] that alerts based on the number of pod replicas deployed.
+///
+/// Note that, as [AlertConfigs](AlertConfig) are agnostic to the type of alert,
+/// it is the caller's responsibility to *not* call this function on other alert
+/// types, like HTTP or gRPC alerts.
 fn replicas_promql(alert_config: &AlertConfig, spec: &ServiceAlertSpec) -> String {
-    match alert_config.operation {
-        Operation::EqualTo => {
-            format!(
-                r#"sum by (app_kubernetes_io_name) (up{{app_kubernetes_io_name="{0}"}}) == {1}"#,
-                spec.deployment_name, alert_config.value,
-            )
-        }
-        Operation::LessThan => format!(
-            r#"sum by (app_kubernetes_io_name) (up{{app_kubernetes_io_name="{0}"}}) < {1}"#,
-            spec.deployment_name, alert_config.value,
-        ),
-        Operation::MoreThan => format!(
-            r#"sum by (app_kubernetes_io_name) (up{{app_kubernetes_io_name="{0}"}}) > {1}"#,
-            spec.deployment_name, alert_config.value,
-        ),
-    }
+    let operation = &alert_config.operation;
+    format!(
+        r#"sum by (app_kubernetes_io_name) (up{{app_kubernetes_io_name="{0}"}}) {operation} {1}"#,
+        spec.deployment_name, alert_config.value,
+    )
 }
 
+/// Returns the [`Annotations`] struct for a given [`AlertConfig`].
 fn replicas_annotations(alert_config: &AlertConfig) -> Annotations {
+    // Alert annotations and labels for Prometheus can be templated, using two
+    // pairs of braces.
+    //
+    // Rust uses a single pair of braces for `format!()` macro templating, so
+    // you need to use an extra pair of braces for every literal brace you want
+    // in the string. This is why you see quadruple brace pairs in descriptions!
     match alert_config.operation {
         Operation::EqualTo => Annotations {
             summary: String::from("Replicas reached alert boundary"),
@@ -68,15 +73,13 @@ fn replicas_annotations(alert_config: &AlertConfig) -> Annotations {
         Operation::LessThan => Annotations {
             summary: String::from("Replicas less than alert boundary"),
             description: format!(
-                // quad-braces necessary for escaping within format! macro
                 "{{{{ $value }}}} replicas currently up, expected at least {0}",
                 alert_config.value
             ),
         },
         Operation::MoreThan => Annotations {
             summary: String::from("Replicas more than alert boundary"),
             description: format!(
-                // quad-braces necessary for escaping within format! macro
                 "{{{{ $value }}}} replicas currently up, expected less than {0}",
                 alert_config.value
             ),

src/prometheus/tests.rs

@@ -0,0 +1,47 @@
+use color_eyre::Result;
+use pretty_assertions::assert_eq;
+
+use crate::prometheus::alert::*;
+
+const SERIALIZED_PROM_ALERT: &str = r#"
+groups:
+- name: example
+  rules:
+  - alert: HighRequestLatency
+    expr: job:request_latency_seconds:mean5m{job="myjob"} > 0.5
+    for: 10m
+    labels:
+      severity: page
+      source: cloud
+      owner: service
+    annotations:
+      summary: High request latency
+      description: Request latency over 9000"#;
+
+#[test]
+fn test_serialisation_happy_path() -> Result<()> {
+    let rust_repr = PromAlerts {
+        groups: vec![AlertGroup {
+            name: "example".into(),
+            rules: vec![AlertRules {
+                alert: "HighRequestLatency".into(),
+                expr: r#"job:request_latency_seconds:mean5m{job="myjob"} > 0.5"#.into(),
+                for_: "10m".into(),
+                labels: Labels {
+                    severity: PrometheusSeverity::Page,
+                    source: "cloud".into(),
+                    owner: "service".into(),
+                },
+                annotations: Annotations {
+                    summary: "High request latency".into(),
+                    description: "Request latency over 9000".into(),
+                },
+            }],
+        }],
+    };
+
+    let yaml_repr: PromAlerts = serde_yaml::from_str(SERIALIZED_PROM_ALERT)?;
+    assert_eq!(yaml_repr, rust_repr);
+
+    Ok(())
+}