certspotter-metrics(8)

📦 version 0.25.0, in nixpkgs unstable

💅 NAME 💅

ok so certspotter-metrics — she outputs Prometheus metrics about how certspotter's operation is going. that's literally her whole job, bestie ✨

🦋 SYNOPSIS 🦋

certspotter-metrics [-state_dir PATH]

🎀 DESCRIPTION 🎀

okay so here's the tea: certspotter-metrics reads a certspotter state directory and then writes out Prometheus metrics — in the Prometheus text exposition format, no less — all about how certspotter is progressing with monitoring each Certificate Transparency log. and where do those metrics go? standard output. that's it. that's the vibe. 💖

the intended use (iykyk) is to run certspotter-metrics periodically — like, say, from cron — and expose the output to Prometheus, for example with the prometheus-node-exporter(1) textfile collector. iconic behavior fr fr.

and here's the part that matters, so listen up: certspotter-metrics only reads the state directory. it never modifies it. so it's totally safe to run while certspotter is running, and it also doesn't require certspotter to be running at all. flexible queen 🫶

metrics get output for every log for which certspotter has a state directory — that's $STATE_DIR/logs/LOG_ID, where LOG_ID is the base64url-encoded log ID. a log has a state directory once certspotter has started monitoring it. the log_id label on each metric is the standard base64 encoding (with padding) of the 32-byte log ID defined by RFC 6962. see https://sslmate.com/app/ctlogs for a list of human-friendly names for each log ID — super handy ngl 🧚

⚠️ real talk: certspotter-metrics is experimental, and the metrics may change in a future release. don't get too attached to the exact shape, bestie 😭

✨ OPTIONS ✨

  • -state_dir PATH — the directory where certspotter stores state. defaults to $CERTSPOTTER_STATE_DIR if that's set, or ~/.certspotter otherwise. this should be the same directory used by certspotter(8). like, same one. don't mix them up 💅
  • -version — print version information and exit. short and sweet, we love a quick exit 👑

🌈 METRICS 🌈

heads up: all metrics are gauges with a log_id label identifying the log the metric pertains to. and if a metric doesn't pertain to a log (because certspotter hasn't stored the relevant state for that log yet), the log just doesn't have a sample for that metric. no sample, no problem 🦋

  • certspotter_log_max_sth_size — tree size of the largest signed tree head (STH) certspotter has observed from the log — in other words, the number of entries in the log. absent if certspotter hasn't yet downloaded an STH from the log.
  • certspotter_log_max_sth_timestamp — timestamp, in milliseconds since the Epoch, of the STH reported by certspotter_log_max_sth_size.
  • certspotter_log_download_position — number of entries certspotter has downloaded from the log, including entries that haven't yet been verified.
  • certspotter_log_verified_position — number of entries certspotter has downloaded from the log and verified against an STH. verified? slay.
  • certspotter_log_verified_sth_timestamp — timestamp, in milliseconds since the Epoch, of the most recent STH certspotter has verified for the log. absent if certspotter hasn't verified an STH for the log. the size of this STH is equal to certspotter_log_verified_position. cute little factoid 💖
  • certspotter_log_unverified_sths — number of unverified STHs certspotter is currently storing for the log.
  • certspotter_log_malformed_entries — number of malformed entries certspotter has recorded for the log. certspotter records an entry as malformed when it cannot parse the entry. see certspotter(8) for more information.
  • certspotter_log_health_check_failures — number of failed health checks certspotter has recorded for the log. see certspotter(8) for info about health checks. (yes, more certspotter lore, go read it)

🌸 EXAMPLES 🌸

a crontab(5) entry that exposes metrics to the node_exporter textfile collector every five minutes. and the reason it writes to a temp file and then renames it? so that node_exporter never reads a partially-written file. big brain energy 🧠✨

*/5 * * * * root certspotter-metrics > /var/lib/node_exporter/certspotter.prom.tmp && mv /var/lib/node_exporter/certspotter.prom.tmp /var/lib/node_exporter/certspotter.prom

a Prometheus query to determine download backlog — that's the number of entries in the log that haven't been downloaded yet:

certspotter_log_max_sth_size-certspotter_log_download_position

💜 ENVIRONMENT 💜

  • CERTSPOTTER_STATE_DIR — directory for storing state. overridden by -state_dir. defaults to ~/.certspotter. this should be the same directory used by certspotter(8).
  • STATE_DIRECTORY — directory for storing state, if it's set and certspotter-metrics is running under systemd.

⭐ EXIT STATUS ⭐

certspotter-metrics exits with status 0 on success, 1 on error, or 2 on invalid usage. simple. clean. periodt. 💅

👑 SEE ALSO 👑

certspotter(8) — go read it, i'm begging you 🙈

and that's the whole page bestie!! this one's from the System Manager's Manual, dated 1980-01-01, and it's certspotter-metrics(8) — go forth and expose those metrics, you're gonna ate 🔥💖

📦 where this page comes from