Proposal

Discuss the metric contract and integration model for additional Azure Cosmos DB Change Feed scaler diagnostics before implementing them. Per the review of #8229, these diagnostics are being separated from EPK support, lease-capacity scaling, and HA, which do not depend on diagnostic exports.

Candidate aggregate measurements:

• Total estimated change-feed lag before scaling caps or split-recovery adjustments.
• Active lease count, including individual never-checkpointed active leases.
• Total processor lease count, including caught-up leases.
• Lag-based desired processor replicas before the lease cap.
• Lease-capacity-based desired processor replicas before the lease cap, using active leases normally and total leases in HA mode.

Desired replicas refer to Kubernetes processor replicas, not Cosmos DB partitions. Lease intervals may be EPK subranges and do not necessarily correspond one-to-one to current physical partitions.

Questions for discussion:

• Should these be first-class metric families with explicit units and names, rather than suffixes in the existing keda_scaler_metrics_value metric label? That family's current description refers to HPA inputs, whereas these would be diagnostics only.
• What collector API would support scaler-specific measurements while keeping shared infrastructure decoupled from individual scalers?
• What labels, cardinality limits, and Prometheus/OpenTelemetry semantics should apply?
• How should failed polls and stale measurements be represented (for example, NaN, omission, or another agreed convention)?
• How should publication and cleanup behave across successful cache installation, aborted rebuilds, concurrent installations, refresh, and object deletion without introducing excessive coupling to cache/scale-handler code?

No metric names, lifecycle interface, or implementation approach are proposed as settled here. This issue is for maintainer design agreement before implementation.

Use-Case

Allow dashboards and troubleshooting to distinguish backlog-driven scaling from lease-distribution-driven scaling, explain why a lease cap limits the recommendation, and observe caught-up lease coverage in HA mode without adding extra HPA inputs or per-lease cardinality.

For example, 20 active leases with little total lag and a capacity of four leases per replica can recommend five processor replicas even when lag alone recommends one. A final scaling metric does not expose that distinction.

Is this a feature you are interested in implementing yourself?

Maybe

Anything else?

Related issue: #8088.

Maintainer discussion: #8229 (comment) and #8229 (comment).

The prior prototype used the existing metric-value collectors and ownership hooks tied to successful cache installation/refresh. Review identified that this introduces shared cache/scale-handler coupling for one scaler. Constructor-time ownership was also shown to be unsafe for aborted or out-of-order builds; any future design should account for those cases and stale writes/cleanup from retiring instances. This records the constraints, not a requirement to reuse that prototype.