chore: update properties doc

CONVENTIONS.md

@@ -1,20 +1,28 @@
+<!-- vale off -->
+
 1. Use an active, present tense voice
-2. Do not use any salesy or marketing terms, Do not use adverbs
-3. Use MDX formatting
-4. Do not use the first person, Use "you" or "your team"
-5. Do not use archaic language
-6. Do not use oxymorons
-7. Precede every command with an explanation of what the command does. After the command, provide additional details about the command, such as what the arguments do and why your reader is using them.
-8. Avoid pop culture references, gender assumptions, holidays, hemisphere seasons, and other exclusionary language
-9. Do not tell people how they feel
-10. Explicitly tell the user to create or open each file you’ll have them use.
-11. Like commands, always introduce a file or script by describing its general purpose, then explain any changes that the reader will be making in the file. Without these explanations, readers won’t be able to customize, update, or troubleshoot issues in the long run.
-12. If you’re asking the reader to write code, follow the same approach for commands: introduce the code block with a high-level explanation of what it does. Then show the code, and then call out any important details.
-13. Avoid adverbs and complex language
-14. Use markdown codeblocks with a language and a title
-15. Do not remove any "```" or "//highlight-next-line" text
-16. Do not use the term "this document", when referring to the system or product being documented always use "Mission Control"
-17. For examples using the following structure:
+2. When referring to concepts or resources do not use the term "they", use the name of the concept or resource instead
+3. Do not use any salesy or marketing terms, Do not use adverbs.
+4. Prefer simple language over complex language, target Grade 10 reading level.
+5. Parse the text as Markdown mixed with JSX blocks i.e. MDX
+6. Avoid using more than 1 list in a paragraph or section.
+7. Never remove or reformat JSX or code blocks\
+8. Do not use the first person, Use "you" or "your team"
+9. Do not use archaic language
+10. Do not use oxymorons
+11. Do not refer to "the system" use "Mission Control" instead
+12. Precede every command with an explanation of what the command does. After the command, provide additional details about the command, such as what the arguments do and why your reader is using them.
+13. Avoid pop culture references, gender assumptions, holidays, hemisphere seasons, and other exclusionary language
+14. Do not tell people how they feel
+15. Explicitly tell the user to create or open each file you’ll have them use.
+16. Always introduce a file or script by describing its general purpose, then explain any changes that the reader will be making in the file. Without these explanations, readers won’t be able to customize, update, or troubleshoot issues in the long run.
+17. If you’re asking the reader to write code. introduce the code block with a high-level explanation of what it does. Then show the code, and then call out any important details.
+18. Avoid adverbs and complex language
+19. Use markdown codeblocks with a language and a title
+20. Do not remove any "```" or "//highlight-next-line" text
+21. Follow standard markdown rules provided by markdownlint
+22. Do not use the term "this document", when referring to the system or product being documented always use "Mission Control"
+23. For examples using the following structure:
     Introduction of example
     Example Code
     This example:

canary-checker/docs/comparisons/index.md

@@ -1,6 +1,6 @@
 ---
 title: Comparisons
-sidebar_position: 3
+sidebar_position: 4
 sidebar_custom_props:
-  icon: material-symbols-light:text-compare-outline
+  icon: compare
 ---

canary-checker/docs/concepts/concepts.md

@@ -0,0 +1,11 @@
+---
+title: Concepts
+hide_sidebar: true
+sidebar_position: 2
+sidebar_custom_props:
+  icon: concepts
+---
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />

canary-checker/docs/concepts/expressions/_transform_fields.mdx

@@ -102,9 +102,11 @@
   {
     field: "metrics",
     description: "Add custom metrics to be exported",
-    scheme: "[[]Metric](../metrics/custom-metrics#metric)",
+    scheme: "[]Metric",
     required: false
   },
+
+
   {
     field: "icon",
     description: null,

canary-checker/docs/concepts/expressions/index.md

@@ -1,7 +1,7 @@
 ---
 title: Expressions
 sidebar_custom_props:
-  icon: variable
+  icon: code
 ---
 
 canary-checker can be extended using expressions in 3 ways:

canary-checker/docs/concepts/image-variants.md

@@ -0,0 +1,50 @@
+---
+title: Image Variants
+sidebar_custom_props:
+  icon: docker
+---
+
+Canary checker comes with 3 image variants:
+
+## [Slim](https://github.com/flanksource/canary-checker/blob/master/build/slim/Dockerfile)
+
+- [arkade](https://github.com/alexellis/arkade)
+- jq
+- yq
+- python3
+
+## [Minimal](https://github.com/flanksource/canary-checker/blob/master/build/minimal/Dockerfile)
+
+- [arkade](https://github.com/alexellis/arkade)
+- kubectl
+- [stern](https://github.com/stern/stern)
+- [fblog](https://github.com/brocode/fblog)
+- jq
+- yq
+- [sops](https://github.com//mozilla/sops)
+- PowerShell 7
+  - powershell-yaml
+- python3
+- [azure-cli](https://learn.microsoft.com/en-us/cli/azure/)
+- [gcloud-cli](https://cloud.google.com/sdk/gcloud)
+  - kubectl-oidc
+  - gke-gcloud-auth-plugin
+- [aws-cli](https://aws.amazon.com/cli/)
+
+## [Full](https://github.com/flanksource/canary-checker/blob/master/build/full/Dockerfile)
+
+Everything in the minimal image plus:
+
+- [k6](https://github.com/grafana/k6)
+- OpenJDK Temurin 21
+- [JMeter](https://jmeter.apache.org/)
+- [Robot Framework](https://robotframework.org/)
+- [benthos](https://benthos.dev)
+- [dsq](https://github.com/multiprocessio/dsq)
+- [restic](https://restic.net/)
+
+You can choose which variant to use in the helm chart using:
+
+```bash
+helm install flanksource/canary-checker --set image.type=full
+```

canary-checker/docs/concepts/metrics.mdx

@@ -0,0 +1,117 @@
+---
+title: Metrics
+sidebar_custom_props:
+  icon: dashboard-line
+---
+
+
+Canary Checker works well with Prometheus and exports metrics for every check, the standard metrics included are:
+
+| Metric                                         | Type      | Description                                 |
+| ---------------------------------------------- | --------- | ------------------------------------------- |
+| canary_check                                   | Gauge     | Set to 0 when passing and 1 when failing    |
+| canary_check_success_count                     | Counter   |                                             |
+| canary_check_failed_count                      | Counter   |                                             |
+| canary_check_info                              | Info      |                                             |
+| canary_check_duration                          | Histogram | Histogram of canary durations               |
+
+Some checks like [pod](../../reference/pod) and [http](../../reference/http) expose additional metrics.
+
+
+## Custom Metrics
+
+Canary checker can export custom metrics from any check type, replacing and/or consolidating multiple standalone Prometheus Exporters into a single exporter.
+
+In the example below, exchange rates against USD are exported by first calling an HTTP api and then using the values from the JSON response to create the metrics:
+
+```yaml title="exchange-rates-exporter.yaml" file=<rootDir>/modules/canary-checker/fixtures/minimal/metrics-multiple.yaml
+
+```
+
+Which would output:
+
+```shell
+exchange_rate{from=USD, to=GBP} 0.819
+exchange_rate{from=USD, to=EUR} 0.949
+exchange_rate{from=USD, to=ILS} 3.849
+exchange_rate_api 260.000
+```
+
+### Fields
+
+| Field    | Description                                            | Scheme            | Required |
+| -------- | ------------------------------------------------------ | ----------------- | -------- |
+| `metrics[].name`   | Name of the metric                                     | `string`          | Yes      |
+| `metrics[].value`  | An expression to derive the metric value from          | <CommonLink to="cel">CEL</CommonLink> with [Check Context](#check-context) that returns `float`       | Yes      |
+| `metrics[].type`   | Prometheus Metric Type  | `counter`, `guage`, `histogram`          | Yes      |
+| `metrics[].labels[].name`      | Name of the label                                      | `string`            | Yes      |
+| `metrics[].labels[].value`     | A static value for the label value                     | `float`            |          |
+| `metrics[].labels[].valueExpr` | An expression to derive the label value from          | <CommonLink to="cel">CEL</CommonLink> with [Check Context](#check-context)     |          |
+| `metrics[].labels[].labels`    | Labels for prometheus metric (values can be templated) | `map[string]string` |          |
+
+Expressions can make use of the following variables:
+
+### Check Context
+
+| Fields                    | Description                                | Scheme                                    |
+| ------------------------- | ------------------------------------------ | ----------------------------------------- |
+| `*`              | All fields from the check result                            | See result variables section of the check |
+| **`last_result.results`** | The last result                            |                                           |
+| `check.name`              | Check name                                 | `string`                                  |
+| `check.description`       | Check description                          | `string`                                  |
+| `check.labels`            | Dynamic labels attached to the check       | `map[string]string`                       |
+| `check.endpoint`          | Endpoint (usually a URL)                   | `string`                                  |
+| `check.duration`          | Duration in milliseconds                   | `int64`                                   |
+| `canary.name`             | Canary name                                | `string`                                  |
+| `canary.namespace`        | Canary namespace                           | `string`                                  |
+| `canary.labels`           | Labels attached to the canary CRD (if any) | `map[string]string`                       |
+
+
+## Prometheus Operator
+
+The helm chart can install a `ServiceMonitor` for the prometheus operator, by enabling the serviceMonitor flag
+
+```
+--set serviceMonitor=true
+```
+
+## Grafana
+
+
+Default grafana dashboards are available. After you deploy Grafana, these dashboards can be installed with
+
+```
+--set grafanaDashboards=true --set serviceMonitor=true
+```
+
+![](/img/grafana-dashboard.png)
+
+
+## Stateful Metrics
+
+
+Metrics can be generated from time based data, e.g. logs per minute, logins per second by using the output of one check execution as the input to the next.
+
+```yaml file=<rootDir>/modules/canary-checker/fixtures/elasticsearch/stateful_metrics.yaml
+
+```
+
+This snippet retrieves the `last_result.results.max` value from the last execution ensuring data is not duplicated or missed
+
+```go
+"@timestamp" : {
+  {{-  if last_result.results.max }}
+  "gte": "{{ last_result.results.max }}"
+  {{- else }}
+  "gte": "now-5m"
+  {{- end }}
+}
+```
+
+The max value is saved in the `transform` section using:
+
+```yaml
+#...
+'detail': { 'max': string(json.?aggregations.logs.age.value_as_string.orValue(last_result().?results.max.orValue(time.Now()))) },
+#...
+```