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, individual observation requests still compete based on their own priority and the scheduler's slew and overhead model.
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.
Static
Fixed priority levels that don't change over time.
- What it does: every observation in the queue gets a priority value that's whatever the submitter set. The scheduler picks the highest-priority eligible observation.
- Good for: ToO follow-up, maintenance windows, anywhere "this is more urgent than that" is the policy.
- Pitfall: doesn't enforce fairness — a single user with permission to set high priorities can starve everyone else. Pair with strict queue-access policy.
Schedule-based allocation
Time on the queue is distributed according to a calendar.
- What it does: the queue carries a schedule (calendar entries mapping entity → time window). Observations from a given entity are only considered during that entity's window.
- 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.
Usage-based allocation
Priority adjusts dynamically based on how much observing time each grantee has used relative to their quotas.
- What it does: each grantee's downstream account / grant carries one or more quotas (lifetime, rolling weekly, nightly, …). The scheduler preferentially picks observations from grantees whose current period quotas are least consumed, smoothing usage toward fair-share.
- Good for: fair-share across many users, semester-shaped budgets, anywhere "everyone should get roughly their fair turn" is the policy.
- Pitfall: rewards inactivity — an entity that doesn't observe early in a period builds up priority. If you want to encourage active use, prefer schedule-based.
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) — used by the static prioritization model and as a tiebreaker for the dynamic models.
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
ObservingQueue Schema
Properties
| Name | Type | Description |
|---|---|---|
| id | Integer |
No description |
| queue_type | Enum(maintenance, too, general, calibration, custom) |
No description |
| telescope_id | Integer |
No description |
| name | String(256) |
No description |
| slug | String(256) |
No description |
| description | String(Unbounded) |
No description |
| can_interrupt | Boolean |
Whether or not the queue can interrupt lower priority queues |
| access_prioritization | Enum(default, total_usage, queue_usage, schedule) |
No description |
| order | Integer |
The order used to prioritize queues for a given telescope. Lower values are higher priority. |
| enabled | Boolean |
Whether or not the queue is enabled. Disabled queues will not be scheduled. |
Relationships
| Relationship Name | Type |
|---|---|
| telescope | Telescope |
| access_grants | ObservingQueueAccessGrant |
ObservingQueueAccessGrant Schema
Properties
| Name | Type | Description |
|---|---|---|
| id | Integer |
The unique identifier for the queue access grant. |
| queue_id | Integer |
The ID of the queue to which the allocation belongs. |
| telescope_access_grant_id | Integer |
The ID of the telescope access grant providing access to this queue. |
| order | Integer |
The order used to prioritize this allocation within the queue. Lower values are higher priority. |
| revoked | Boolean |
Whether this allocation has been revoked. If true, the allocation is no longer valid. |
| effective_order | Integer |
The effective order used to prioritize thisa llocation within the queue, taking into account the queue's prioritization policy and the allocation's own priority. |
| time_used | Float |
The total time used by the account regardless of whether it was contested or not. |
| time_contested | Float |
The total time used by the account when sibling accounts also had observations which could have been scheduled. |
| time_waiting | Float |
The total time that the other accounts used while this account was waiting for its observations to be scheduled. |
| observing_policy_id | Integer (Optional) |
No description |
Relationships
| Relationship Name | Type |
|---|---|
| queue | ObservingQueue |
| telescope_access_grant | TelescopeAccessGrant |
| observing_accounts | ObservingAccount |
| observing_policy | ObservingPolicy |
ObservingScheduleEvent Schema
Properties
| Name | Type | Description |
|---|---|---|
| id | Integer |
No description |
| owner_id | Integer (Optional) |
No description |
| telescope_id | Integer (Optional) |
No description |
| priority | Integer |
No description |
| created_on | DateTime |
No description |
| updated_on | DateTime (Optional) |
No description |
| start_on | DateTime (Optional) |
No description |
| end_on | DateTime (Optional) |
No description |
| end_time_unspecified | Boolean |
No description |
| all_day | Boolean |
No description |
| recurrence | String(100) (Optional) |
No description |
| recurring_event_id | Integer (Optional) |
No description |
| is_too | Boolean |
No description |
| is_exclusive | Boolean |
No description |
| description | String(100) |
No description |
Relationships
| Relationship Name | Type |
|---|---|
| owner | Organization |
| telescope | Telescope |
| users | User |
| groups | Group |
| organizations | Organization |
| observations | Observation |
SchedulerRun Schema
Properties
| Name | Type | Description |
|---|---|---|
| id | Integer |
No description |
| started_at | DateTime |
No description |
| finished_at | DateTime (Optional) |
No description |
Relationships
| Relationship Name | Type |
|---|---|
| tasks | ObservationTask |