[DISCUSS] Add bounded scheduler summary endpoint for agentic/LLM debugging

[Mit Desai <mi...@gmail.com>]

Hi Everyone,

As more operators adopt agentic and LLM-based tooling for cluster
observability, I would like to propose a small, additive enhancement to our
REST API to address a current limitation.

The /ws/v1/fullstatedump endpoint is valuable for offline debugging, but
its response size grows with cluster scale, often reaching hundreds of
megabytes. This makes it impractical as a real-time signal source for
automated tooling and LLM agents with finite context windows. While our
individual drill-down endpoints handle depth well, we lack a "bounded
breadth" layer that provides a high-level cluster overview in a predictably
small response.

I propose adding a new endpoint: GET /ws/v1/scheduler/summary.

This endpoint would return a compact digest of the scheduler state,
including queue saturation signals, application counts by state, and the
top-N longest-waiting pending applications with their failure reasons. The
response size would be bounded at O(queue count) + O(20 stalled apps),
regardless of cluster size.

Key details:

- Scope: This is a purely additive change. It does not modify existing
handler logic or the fullstatedump endpoint.
- Consistency: It fits within the /ws/v1/scheduler/ prefix and follows
established DAO and handler patterns.
- Alternatives: Existing sub-endpoints require a cluster map to be useful,
which is the gap this summary fills. Field selection parameters do not
solve the cardinality problem within large sections like nodes.

I would appreciate the community’s feedback on:

1. Whether this fits our long-term REST API direction.
2. Any concerns regarding maintenance burden or API surface area?


Thanks,
Mit