Merge pull request #50 from flanksource/transform-docs

chore: add docs for transform
flanksource · Apr 16, 2023 · e10d471 · e10d471
2 parents 2013130 + 8d89b58
commit e10d471
Show file tree

Hide file tree

Showing 3 changed files with 58 additions and 8 deletions.
diff --git a/docs/canary-checker/concepts/templating.md b/docs/canary-checker/concepts/templating.md
@@ -69,4 +69,42 @@ file:
 ```
 The fields, `type`, and `id` require a JSONPath expression to run. The string `$.Config.InstanceType` and `$.Config.InstanceId` specify the JSON value for `InstanceType` and `InstanceId` respectively contained in the files set in `path`.
 
+## Transformation
 
+The `transform` can be used to convert one canary check into multiple checks programatically. 
+
+??? example
+
+    ```yaml
+    apiVersion: canaries.flanksource.com/v1
+    kind: Canary
+    metadata:
+      name: alertmanager-check
+    spec:
+      schedule: "*/5 * * * *"
+      alertmanager:
+        - host: alertmanager.example.com
+          alerts:
+            - .*
+          ignore:
+            - KubeScheduler.*
+          transform:
+            javascript: |
+              var out = _.map(results, function(r) {
+                return {
+                  name: r.name,
+                  labels: r.labels,
+                  icon: 'alert',
+                  message: r.message,
+                  description: r.message,
+                }
+              })
+              JSON.stringify(out);
+    ```
+
+In the above example, the check will return multiple alerts from alertmanager. By default, all of those alerts will be grouped in a single check.
+
+But if we want to display each alert as its own check in the UI, we can use the `transform` function for this. The transform function takes a `Template` as input and the output from the template expected
+are the checks in JSON format. Only the `name`, `labels`, `icon`, `message` and `description` fields need to be populated, others fields are generated automatically.
+
+For example, if there are 9 different alerts, each alert will have its own check that can be managed and interacted with equally.
diff --git a/docs/canary-checker/overview.md b/docs/canary-checker/overview.md
@@ -37,4 +37,4 @@ If any one of these checks fails, (e.g: the service doesn't respond after 3000 m
 | Prometheus                                              | canary-checker is not a replacement for prometheus, rather a companion. While prometheus provides persistent time series storage, canary-checker only has a small in-memory cache of recent checks.  Canary-checker also exposes metrics via `/metrics` that are scraped by prometheus. |
 | Grafana                                                 | The built-in UI provides a mechanism to display check results across 1 or more instances without a dependency on grafana/prometheus running. The UI  will also display long-term graphs of check results by quering prometheus. |
 | [Kuberhealthy](https://github.com/Comcast/kuberhealthy) | Very similar goals, but Kuberhealthy relies on external containers to implement checks and does not provide a UI or multi-cluster/instance aggregation. |
-| [Cloudprober](https://cloudprober.org/)                 | Very similar goals, but Cloudprober is designed for very high scale, not multi-tenancy. Only has ICMP, DNS, HTTP, UDP built-in checks. |
+| [Cloudprober](https://cloudprober.org/)                 | Very similar goals, but Cloudprober is designed for very high scale, not multi-tenancy. Only has ICMP, DNS, HTTP, UDP built-in checks. |
diff --git a/docs/canary-checker/reference/alert-manager.md b/docs/canary-checker/reference/alert-manager.md
@@ -8,15 +8,27 @@ This checks [Prometheus AlertManager](https://prometheus.io/docs/alerting/latest
     apiVersion: canaries.flanksource.com/v1
     kind: Canary
     metadata:
-      name: cloudwatch-check
+      name: alertmanager-check
     spec:
       schedule: "*/5 * * * *"
       alertmanager:
-        - auth:
-            username:
-              value: admin
-            password:
-              passowrd: secretpassword
+        - host: alertmanager.example.com
+          alerts:
+            - .*
+          ignore:
+            - KubeScheduler.*
+          transform:
+            javascript: |
+              var out = _.map(results, function(r) {
+                return {
+                  name: r.name,
+                  labels: r.labels,
+                  icon: 'alert',
+                  message: r.message,
+                  description: r.message,
+                }
+              })
+              JSON.stringify(out);
     ```
 
 | Field         | Description                                        | Scheme                              | Required |
@@ -28,7 +40,7 @@ This checks [Prometheus AlertManager](https://prometheus.io/docs/alerting/latest
 | `test`        | Template to test the result against                | [`Template`](#template)             |          |
 | `display`     | Template to display the result in                  | [`Template`](#template)             |          |
 | `transform`   | Template for transformation                        | [`Template`](#template)             |          |
-| `host`        | Template for transformation                        | `string`                            |          |
+| `host`        | Host endpoint                                      | `string`                            |          |
 | `auth`        | Credentials for AlertManager                       | [`Authentication`](#authentication) |          |
 | `alerts`      | Cloudwatch HTTP Endpoint to establish connection   | `[]string`                          |          |
 | `filters`     | Used to filter the objects                         | `map[string]string`                 |          |