docs: Start documentation on prometheus metrics

1 files changed, 56 insertions, 0 deletions

diff --git a/docs/metrics.md b/docs/metrics.md
new file mode 100644
index 0000000..b2b3445
--- /dev/null
+++ b/docs/metrics.md
@@ -0,0 +1,56 @@
+# Metrics
+
+The `silentct-mon` program emits Prometheus metrics -- enable using the `-m`
+option.  For a *bash example* of how to create appropriate alerts from these
+Prometheus metrics, see [scripts/silentct-check](../scripts/silentct-check).
+
+## `"silentct_log_size"`
+
+```
+# HELP silentct_log_size The number of entries in the log.
+# TYPE silentct_log_size gauge
+silentct_log_size{id="TnWjJ1yaEMM4W2zU3z9S6x3w4I4bjWnAsfpksWKaOd8="} 6.07308178e+08
+```
+
+`id` is a unique log identifier in base64 (computed as in RFC 6962, §3.2).
+
+## `"silentct_log_index"`
+
+```
+# HELP silentct_log_index The next log entry to be downloaded.
+# TYPE silentct_log_index gauge
+silentct_log_index{id="TnWjJ1yaEMM4W2zU3z9S6x3w4I4bjWnAsfpksWKaOd8="} 6.07307424e+08
+```
+
+`id` is a unique log identifier in base64 (computed as in RFC 6962, §3.2).
+
+## `"silentct_log_timestamp"`
+
+```
+# HELP silentct_log_timestamp The log's UNIX timestamp in ms.
+# TYPE silentct_log_timestamp gauge
+silentct_log_timestamp{id="TnWjJ1yaEMM4W2zU3z9S6x3w4I4bjWnAsfpksWKaOd8="} 1.735992491111e+12
+```
+
+`id` is a unique log identifier in base64 (computed as in RFC 6962, §3.2).
+
+## `"silentct_certificate_alert"`
+
+```
+# HELP silentct_certificate_alert The time the certificate without allowlisting was found.
+# TYPE silentct_certificate_alert gauge
+silentct_certificate_alert{stored_at="/path/to/state/crt_found/<log-hex-id>-<log-index>.json"} 1.735992551e+09
+```
+
+`stored_at` is where the log entry is stored on the monitor's local file system.
+For convenience, the parsed log-entry certificate is also available as `.der`.
+
+## `"silentct_error_counter"`
+
+```
+# HELP silentct_error_counter The number of errors propagated to the main loop.
+# TYPE silentct_error_counter counter
+silentct_error_counter 0
+```
+
+Do not use for alerting, this metric is too noisy and currently used for debug.