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," "education," "PI X's program," "engineering / maintenance." Within a queue, the queue's prioritization model orders the access grants, and each grantee's own account ordering and observation priorities order the work inside their slice — see Scheduler prioritization for the full ladder.

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

Anatomy of a queue¶

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

Identity — name, description, ownership.
Telescope binding — every queue belongs to exactly one telescope.
Position in the order — the queue's index in the telescope's ordered list.
Prioritization model — see below.
Observing policy — the policy the queue is bound to (operational constraints, batching rules, etc.). See Observing policy.
Access grants — one or more ObservingQueueAccessGrants saying which entities can put observations through this queue.
Schedule events — the scheduler's history on this queue.

Queues can be reordered, paused, or removed at any time without deleting underlying observations. Reordering takes effect at the next scheduler run.

Prioritization models¶

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 order the queue's access grants — it produces each grant's effective_order, which the scheduler then uses directly (see Scheduler prioritization).

Fixed¶

Grant priorities you set by hand, unchanged by usage.

What it does: each queue access grant keeps whatever order you configured; the scheduler always considers grants in that order.
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 — the top-ordered grant can starve everyone below it whenever it has work queued. Use it where that's the intent.

Grant priorities adjust dynamically so every grantee trends toward their ownership fraction — their shares on the telescope access grant.

What it does: the scheduler continuously reorders 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).
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.

Calendar¶

Time on the queue is distributed according to a schedule.

What it does: the queue carries calendar entries mapping grantee → time window. During a grantee's window their grant is at the top of the queue; outside it, the grant isn't considered.
Good for: classroom programs ("students get Mondays"), seasonal collaborations, formal time allocations.
Pitfall: unused windows go unused — if the entity with the slot hasn't queued anything, the queue is idle. Use with a backup queue one priority level down.

Queue access grants¶

ObservingQueueAccessGrant records say "this entity may submit observations through this queue, with this weight." They are the mechanism by which time on a queue is allocated to a user, organization, or group.

A grant carries:

The queue it applies to.
The grantee entity.
An observing-policy reference (or inherits the queue's default).
Relative priority within the queue (order / effective_order) — under the fixed prioritization model effective_order is exactly the configured order; under the dynamic models the mode recomputes effective_order and the configured order breaks ties between grants the mode considers equal.

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.

Like telescope access grants, queue access grants can be issued in invited state to entities that haven't yet accepted; see the access grants page for how the invitation flow works.

Editing queues in the web app¶

The owner-facing UI for queue editing is at org-telescope-queues.tsx in the React port, with the Angular equivalent at apps/website/src/app/features/entity/telescopes/telescope-queues/ (including a queue editor dialog).

In the API, queues themselves are managed through the dedicated observing_queues router; queue access is managed via the observing_queue_access_grants router.

Schedule events and scheduler runs¶

The scheduler runs at a regular cadence and emits ObservingScheduleEvent records per queue (essentially: "I considered the queue at time T, here's what won"). The SchedulerRun record gives you the per-run summary across all telescopes.

Read these — they're the easiest way to diagnose "why didn't my observation run" without diving into the scheduler logs.

Reference¶