Add reconciliation metrics and Kubernetes events

CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+* Reconciliation metrics. `Controller::with_observer` reports every
+  reconciliation pass to a `ReconcileObserver`, with its `Phase` (`init`,
+  `apply`, `cleanup`, or `delete`), `Outcome` (`completed`, `waiting`,
+  `skipped`, `failed`, or `abandoned`), and duration. Reconcilers can time
+  named steps of their work with `TraceMetadata::step`, and override a
+  pass's outcome with `TraceMetadata::set_outcome`. Passes cancelled mid-way
+  (for instance, on losing a leadership lease) are reported as abandoned.
+* `PrometheusMetrics`, behind the new `prometheus` feature, a
+  `ReconcileObserver` exporting `<namespace>_reconciliations_total`,
+  `<namespace>_reconciliation_duration_seconds`,
+  `<namespace>_reconciliation_steps_total`, and
+  `<namespace>_reconciliation_step_duration_seconds`, with histogram
+  buckets from 10ms to 30s by default.
+* Kubernetes events, in the new `events` module. `EventRecorder` publishes
+  `events.k8s.io/v1` events on behalf of one controller, aggregating
+  identical repeats into a single event's series, truncating overlong
+  notes, and giving up after a timeout (5 seconds by default).
+  `Controller::with_event_recorder` publishes an event on the resource
+  whenever reconciling it fails, as determined by the new
+  `Context::failure_event` hook, and enables `TraceMetadata::publish_event`
+  for reconcilers' own events.
+* The `conditions` module, for maintaining a resource's standard
+  `status.conditions`. `conditions::set` applies a `DesiredCondition`,
+  keeping `lastTransitionTime` unless the condition's status changes, and
+  reports whether anything changed (and so whether the status needs
+  writing). `conditions::find_observed` ignores conditions determined from
+  an older generation of the resource.
+* `Controller::with_name`, naming a controller in its metrics and tracing
+  span.
+* `Error` is now exported, along with `Error::display_chain`, so that
+  `Context::error_action` can be overridden outside this crate.
+
+### Changed
+
+* The `controller` field of the `reconcile` tracing span now defaults to the
+  resource kind for contexts without a finalizer, rather than being empty.
+* The `reconcile` tracing span has a new `outcome` field.
+
 ## [0.12.0] - 2026-07-22
 
 ### Added

Cargo.toml

@@ -18,16 +18,23 @@ futures = "0.3"
 k8s-openapi = { version = "0.27.0", default-features = false }
 kube = { version = "3.0.0", default-features = false, features = ["client"] }
 kube-runtime = "3.0.0"
+prometheus = { version = "0.14", default-features = false, optional = true }
 rand = "0.9.2"
 serde = "1"
 serde_json = "1"
 thiserror = "2.0.17"
-tokio = { version = "1", features = ["time"] }
+tokio = { version = "1", features = ["sync", "time"] }
 tracing = "0.1"
 
+[features]
+# Provides `PrometheusMetrics`, a `ReconcileObserver` exporting Prometheus metrics.
+prometheus = ["dep:prometheus"]
+
 [dev-dependencies]
+http = "1"
 k8s-openapi = { version = "0.27.0", default-features = false, features = ["v1_34"] }
-tokio = "1"
+tokio = { version = "1", features = ["rt"] }
+tower = { version = "0.5", features = ["util"] }
 
 [package.metadata.docs.rs]
-features = ["k8s-openapi/latest"]
+features = ["k8s-openapi/latest", "prometheus"]

README.md

@@ -67,3 +67,11 @@ loop {
     sleep(Duration::from_secs(1));
 }
 ```
+
+## Observability
+
+Controllers can report reconciliation metrics to a `ReconcileObserver`
+(with a Prometheus implementation behind the `prometheus` feature), and
+publish Kubernetes events on resources whose reconciliation fails. The
+`conditions` module maintains standard `status.conditions`. See the crate
+documentation for details.