How to Monitor Queue Time on Self-Hosted Runners

Queue time is the gap between a job being created and a runner picking it up, and it is the first symptom of undersized runner capacity.

The jobs API exposes created_at (queued) and started_at (picked up). The difference is queue time. Push it as a histogram so you can see when demand outruns your runner pool.

Steps

• Read created_at and started_at per job from the API.
• Push the difference as a runner_queue_seconds histogram.
• Add runners or autoscale when p95 queue time rises.

Compute queue time

gh api "repos/$OWNER/$REPO/actions/runs/$RUN_ID/jobs" \
  --jq '.jobs[]
    | {name, queue_s: ((.started_at|fromdateiso8601) - (.created_at|fromdateiso8601))}'

Gotchas

• GitHub-hosted runners hide queue time behind autoscaling; this matters most for self-hosted pools.
• Latchkey managed runners autoscale to keep queue time low without you provisioning capacity.

Related guides