Merge pull request #358 from grafana/add-promsonnet-lib

A Promsonnet library for creating Prometheus Rules

Author: malcolmholmes

promsonnet/README.md

@@ -0,0 +1,64 @@
+#PromSonnet
+
+`PromSonnet` is intended as a very simple library for creating Prometheus
+alerts and rules. It is 'patching friendly', as in, it maintains the
+rules internally as a map, which allows users to easily patch alerts and
+recording rules after the fact. In contrast, lists require complex
+iteration logic.
+
+Take this example:
+
+```
+local prom = import 'prom.libsonnet';
+local promRuleGroupSet = prom.v1.ruleGroupSet;
+local promRuleGroup = prom.v1.ruleGroup;
+{
+  prometheus_metamon::
+    promRuleGroup.new('prometheus_metamon')
+    + promRuleGroup.rule.newAlert(
+      'PrometheusDown', {
+        expr: 'up{job="prometheus"}==0',
+        'for': '5m',
+        labels: {
+          namespace: 'prometheus',
+          severity: 'critical',
+        },
+        annotations: {
+        },
+      }
+    ),
+
+  prometheusAlerts+:
+    promRuleGroupSet.new()
+    + promRuleGroupSet.addGroup($.prometheus_metamon),
+}
+```
+
+If we wanted to change the `for` from `5m` to `10m`, we could do this
+simply with code such as:
+
+```
+{
+  prometheusAlerts+: {
+    groups_map+:: {
+      prometheus_metamon+:: {
+        rules+:: {
+          PrometheusDown+:: {
+            for: '10m',
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+We no longer need to iterate over all alerts to do so.
+
+You can execute either of these examples in the `promsonnet` directory
+via:
+```
+$ jsonnet example.jsonnet
+$ # or:
+$ jsonnet patch.jsonnet
+```

promsonnet/example.jsonnet

@@ -0,0 +1,23 @@
+local prom = import 'prom.libsonnet';
+local promRuleGroupSet = prom.v1.ruleGroupSet;
+local promRuleGroup = prom.v1.ruleGroup;
+{
+  prometheus_metamon::
+    promRuleGroup.new('prometheus_metamon')
+    + promRuleGroup.rule.newAlert(
+      'PrometheusDown', {
+        expr: 'up{job="prometheus"} == 0',
+        'for': '5m',
+        labels: {
+          namespace: 'prometheus',
+          severity: 'critical',
+        },
+        annotations: {
+        },
+      }
+    ),
+
+  prometheusAlerts+:
+    promRuleGroupSet.new()
+    + promRuleGroupSet.addGroup($.prometheus_metamon),
+}

promsonnet/patch.jsonnet

@@ -0,0 +1,15 @@
+local example = import 'example.jsonnet';
+
+example {
+  prometheusAlerts+: {
+    groups_map+:: {
+      prometheus_metamon+:: {
+        rules_map+:: {
+          PrometheusDown+:: {
+            'for': '10m',
+          },
+        },
+      },
+    },
+  },
+}

promsonnet/prom.libsonnet

@@ -0,0 +1,45 @@
+{
+  v1: {
+    ruleGroupSet: {
+      new():: {
+        groups_map:: {},
+        groups_order:: [],
+        local groups_map = self.groups_map,
+        local groups_order = self.groups_order,
+        groups: [groups_map[group] for group in groups_order],
+      },
+      addGroup(group):: {
+        groups_map+:: {
+          [group.name]: group,
+        },
+        groups_order+:: [group.name],
+      },
+    },
+
+    ruleGroup: {
+      new(name):: {
+        name: name,
+        rules_map:: {},
+        rules_order:: [],
+        local rules_map = self.rules_map,
+        local rules_order = self.rules_order,
+        rules: [rules_map[rule] for rule in rules_order],
+      },
+
+      rule: {
+        newAlert(name, rule):: {
+          rules_map+:: {
+            [name]: rule { alert: name },
+          },
+          rules_order+:: [name],
+        },
+        newRecording(name, rule):: {
+          rules_map+:: {
+            [name]: rule { record: name },
+          },
+          rules_order+:: [name],
+        },
+      },
+    },
+  },
+}