Skip to content

Observing queues

An observing queue is a named lane of time on a telescope. Each telescope carries an ordered list of queues, and the scheduler considers queues in that order: higher-priority queues drain first, lower ones fill the gaps.

Queues exist to coarsely partition telescope time between audiences and programs — “ToO follow-up,” “general observing,” “calibration,” “engineering / maintenance.” When Skynet staff set up a newly registered telescope, it gets four queues in this order: Maintenance, TOO, Calibration, and General. Within a queue, the queue’s prioritization model orders the access grants, and each grantee orders the work inside its own slice through its accounts and grants — see Queue prioritization for the full chain. You never need a queue per grantee: a grantee’s internal priorities live inside its own observing accounts.

If you’re new to the access model, read Telescope access first — this page goes deeper on queues specifically.

A queue is its own first-class record (ObservingQueue). It carries:

  • Identity — name, description, type (maintenance, ToO, general, calibration, or custom).
  • Telescope binding — every queue belongs to exactly one telescope.
  • Level on the telescope — the queue’s position in the telescope’s ordered list. Lower is higher priority. The list is strict: no two queues on a telescope share a level.
  • Prioritization model — see below.
  • Interrupt flag (canInterrupt) — recorded and shown on the queue page as whether this lane may pre-empt a running task from a lower lane. The scheduler does not read it today: a running task is never pre-empted because of queue priority.
  • Access grants — one or more ObservingQueueAccessGrants saying which entities can put observations through this queue.

Queues can be renamed, reordered, or disabled at any time without deleting underlying observations; a disabled queue is skipped by the scheduler. Owners cannot create or delete queues or change a queue’s type. Reordering takes effect at the next scheduler run.

Each queue selects exactly one prioritization model. They are not combinable; pick the one that matches the policy you actually want. The model’s job is to give each of the queue’s access grants an effective level, which the scheduler then uses directly (see Queue prioritization). In the app the models are labeled Default (fixed), Total usage and Queue usage (the two fair-share scopes), and Schedule-driven (calendar).

Grant levels you set by hand, unchanged by usage.

  • What it does: each queue access grant keeps whatever level you configured; the scheduler always considers grants in that order. The list is strict — one grantee per level, and a new grant joins at the bottom. To treat grantees as equals, choose a fair-share mode instead.
  • Good for: ToO follow-up (“the rapid-response program always outranks everyone”), maintenance windows, anywhere the allocation policy is fully manual.
  • Pitfall: doesn’t enforce fairness — a top-level grant can starve everyone below it whenever it has work queued. Use it where that’s the intent.

Fair-share (telescope-wide or queue-local)

Section titled “Fair-share (telescope-wide or queue-local)”

Grant levels are meant to adjust dynamically so every grantee trends toward their ownership fraction — their shares on the telescope access grant. This is not live yet: today every grant in a fair-share queue is an equal peer, and the contested-time accounting it depends on runs only as a logged diagnostic.

  • What it is designed to do: the scheduler continuously re-levels the queue’s grants so that grantees running behind their share float to the top and grantees running ahead sink. Usage is measured on contested time only: time a grantee used while nobody else was waiting is free and doesn’t move their standing (use-it-or-lose-it — idle-time usage can’t be hoarded and can’t be held against anyone; see How usage is counted). Your static levels break ties between grantees at the same standing.
  • Two scopes: telescope fair-share measures each grantee’s contested usage across the whole telescope (this queue compensates for imbalance anywhere); queue fair-share measures only usage within this queue (a self-contained allocation).
  • Good for: fair division among many grantees, shared community telescopes, anywhere “everyone gets their fraction under contention” is the policy.
  • Pitfall: shares promise contested priority, not absolute hours — a grantee with big shares and no queued work simply leaves the time to others, free.

Grant levels are meant to follow a schedule you define. This is not built: periods cannot be defined yet, and today every grant in a calendar queue is an equal peer.

  • What it is designed to do: you define periods on the queue — a date range, optionally recurring — and inside each period you assign the queue’s grants their levels for that period. Outside every period, and for any grant a period doesn’t mention, the static levels apply. It is an alternative to fixed and fair-share, not a lock-out: every grantee stays eligible at all times; a period only changes who goes first.
  • Good for: rotating arrangements (“institution X has priority in week one, institution Y in week two, repeating”), classroom terms, seasonal collaborations, formal time allocations.

ObservingQueueAccessGrant records say “this entity may submit observations through this queue, at this level.” They are the mechanism by which time on a queue is allocated to a user or organization.

A grant carries:

  • The queue it applies to.
  • The grantee entity (through its telescope access grant).
  • An optional observing-policy reference (policies are recorded but not yet enforced; see Observing policy).
  • Its static level within the queue (order), and an effective level (effectiveOrder) reserved for the dynamic modes. The scheduler does not maintain or read the effective level today: fixed queues use the static level, and fair-share and calendar queues treat their grants as peers.

An entity holds at most one access grant per queue, and every observing account of that entity draws on the same grant. An observing account, in turn, references at most one queue per telescope — so when a grantee’s members pick an account they are picking the lane, and a grant on a ToO or maintenance lane is only ever reached on purpose.

Note: the ObservingQueueAccessGrant is the queue-side wiring; the quotas that actually throttle credit consumption live on the downstream ObservingAccount or ObservingGrant records, not on the queue access grant. See Observers → Observing accounts → Quotas.

Queue access grants are created together with, or added to, a telescope access grant; when that grant is an outstanding email invitation, its queue access grants take effect once the invitation is accepted. See Telescope access grants. Revoking a queue access grant that observing accounts still reference marks it revoked; it can be reinstated later.

Owners and device managers change queues on the telescope’s Queues tab: queue order, each queue’s name, description, prioritization, interrupt flag and enabled state, and the order of a fixed queue’s access grants. The steps are in Configure queues. Grantees are added to and removed from queues on the telescope’s Access Grants tab; see Grant access.

In the API, queues are managed under the telescope (the telescope and queue path segments take a uid or slug): GET /v1/telescopes/{telescope}/queues, PATCH /v1/telescopes/{telescope}/queues/{queue}, and PUT /v1/telescopes/{telescope}/queues/order (renumbers the whole list in one call). A queue’s access grants are at /v1/telescopes/{telescope}/queues/{queue}/access-grants (list and create, PATCH / DELETE one, POST …/{grant_uid}/reinstate, and PUT …/access-grants/order); a cross-telescope view is at /v1/observing-queue-access-grants.

The scheduler runs at a regular cadence, and every task it places is stamped with the queue access grant and observing grant it ran under. The telescope’s Schedule tab shows what was planned; those stamps are what to read first when diagnosing “why didn’t my observation run” without diving into the scheduler logs.