A Prometheus exporter for useful Kubernetes CronJob metrics.
cronometer is a single Go binary which watches pods belonging to Cronjobs in a Kubernetes cluster and exports success/failure metrics in Prometheus format. These metrics can be visualised in Grafana (or your favourite visualisation tool).
The example deployment in this repo spins up a Grafana dashboard. Sneak peek:
- Export per-execution CronJob metrics (success/failure and duration)
- Simple PromQL: calculate success rate and latency distributions without joins
- Drop-in deployment alongside kube-prometheus-stack
- Lightweight: single Go binary, no CRDs.
cronometer exports the following prometheus metrics:
| Metric | Description | Labels |
|---|---|---|
| cronometer_cronjob_started_total | counter of started executions | cronjob_name, namespace |
| cronometer_cronjob_completed_{count,sum,bucket} | histogram of completed job durations | cronjob_name, namespace, outcome |
kube-state-metrics is commonly used to export metrics describing Kubernetes API objects.
It exposes the following metrics:
| Metric |
|---|
| kube_cronjob_created |
| kube_cronjob_info |
| kube_cronjob_metadata_resource_version |
| kube_cronjob_next_schedule_time |
| kube_cronjob_spec_failed_job_history_limit |
| kube_cronjob_spec_successful_job_history_limit |
| kube_cronjob_spec_suspend |
| kube_cronjob_status_active |
| kube_cronjob_last_schedule_time |
| kube_cronjob_last_successful_time |
The philosophy of kube-state-metrics is to "generate metrics from Kubernetes API objects without modification ... exposing raw data unmodified from the Kubernetes API".
A consequence of this is that while these metrics are useful for answering basic observability questions about CronJob objects ("When did my CronJob last run successfully?" "Is my CronJob currently running"), they make it hard to answer questions which need to know about CronJobs and Pods, like "What is the success rate of executions of my CronJob?". At least without writing complex PromQL queries. Or writing a Prometheus exporter...
The example deployment includes:
- kube-prometheus-stack - provides prometheus, grafana
- metrics-server - lets us see how much CPU / memory cronometer is using
- cronometer
- some CronJobs - examples to monitor
By far the simplest way to spin up the example is to use KinD. A Makefile is provided for convenience.
Pre-requisites:
- KinD
- helm
- make
- kubectl (k9s optional but recommended)
Deploying the example:
# deploys the example to a KinD cluster called cronometer-demo
make kind-upAccessing the example Dashboard:
# get grafana admin password
kubectl --namespace default get secrets kube-prometheus-stack-grafana -o jsonpath="{.data.admin-password}" | base64 -d ; echo
# port forward the grafana service with kubectl (k9s makes this easier!)
kubectl port-forward svc/kube-prometheus-stack-grafana 3000:80The dashboard should now be available at http://127.0.0.1:3000/d/cronometer/cronometer
Note: The PromQL in the dashboard calculates rate over 5 minute windows, so you will need to wait 5 minutes for the first data to show in the status history panel.
The example also contains all the dashboards which come with kube-prometheus-stack.
To build and deploy checked-out code, see development setup.
Contributions are very welcome - and not limited to code!
Some examples of contributions which are not code changes could be:
- Opening an issue to request a feature or report a bug.
- Improving documentation (fixing typos, clarifying setup, adding examples).
- Extending platform support (e.g. linux_arm64).
- Providing constructive feedback on issues and PRs.
Note that there has traditionally been a high barrier to entry to contribution to open source software projects. This repo aims to be as accessible as possible to challenge this and enable people to contribute (perhaps for the first time). If you feel an area of the documentation is unclear, please do not hesitate to open an issue, or PR.
If you have an idea for a code contribution but aren't sure how to get started, feel free to open an issue and I will try to help.
See CONTRIBUTING.md for specific rules and guidelines before contributing.
First-time contributors are especially welcome 🚀
MIT License.