CI / Speed and debugging
Measure how fast CI jobs start
Your CI jobs take long to start, and you want to know which part is slow before you change container sizes or limits. The startup diagnostic workflow measures these parts on Source, with no install and no test suite.
3 min read
A local run cannot measure Cloudflare provisioning or the container queue of the account. So this measurement runs on Source.
You need:
- Write access to a repository on Source, to push the workflow and start it.
- The
srcCLI, logged in.
1. Add the diagnostic workflow
Create .source/workflows/startup-diagnostic.ts. This is the diagnostic workflow of the TanStack Source repository:
import { defineWorkflow, manual } from '@tanstack-source/ci'
// No install or test suite: the forge's job record measures provisioning and checkout.
// Run twice on the same ref to compare a fresh plan/cache with their cached paths.
const probe = {
name: 'First command',
run: `node -e 'console.log(JSON.stringify({firstCommandAt:Date.now(),node:process.version,arch:process.arch}))'`,
}
const common = { timeoutMinutes: 5, checkout: { depth: 1, lfs: false } } as const
export default defineWorkflow('startup-diagnostic', { on: [manual()], cancelOlderRuns: false })
.job('node-small', { ...common, image: 'node', size: 'small', steps: [probe] })
.job('node-large', { ...common, image: 'node', size: 'large', steps: [probe] })
.job('browser-large', { ...common, image: 'browser', size: 'large', steps: [probe] })
.job('restore', {
...common,
image: 'node',
size: 'large',
warm: { files: ['.source/workflows/startup-diagnostic.ts'], through: 'Prepare restore fixture' },
steps: [
// Every step runs on a restored snapshot too: the fixture is made only when the snapshot did not bring it.
{
name: 'Prepare restore fixture',
run: 'if [ -f node_modules/startup-diagnostic.bin ]; then echo "The fixture came from the snapshot."; else mkdir -p node_modules && dd if=/dev/urandom of=node_modules/startup-diagnostic.bin bs=1048576 count=16 status=none; fi',
},
probe,
{ name: 'Check restored bytes', run: 'test "$(wc -c < node_modules/startup-diagnostic.bin)" -eq 16777216' },
],
})
- It has only a manual trigger, no secrets, no external network access, and a five-minute limit per job.
- It compares small and large Node containers, the browser image, and a job with a warm start,
restore.
Push it to a branch in your repository.
2. Start it on that branch
Replace OWNER/REPO and BRANCH:
src api repos/OWNER/REPO/ci/workflows/startup-diagnostic/runs -X POST -f ref=BRANCH
3. Get the jobs of the run
Read the returned run id, then get its jobs:
src api repos/OWNER/REPO/ci/runs/RUN_ID
4. Read the timings of each job
For each jobId that is not null, read its lifecycle timings and its log:
src api repos/OWNER/REPO/jobs/JOB_ID --jq '{createdAt,provisioningAt,startedAt,completedAt,steps}'
src api repos/OWNER/REPO/ci/runs/RUN_ID/jobs/node-large/logs --include
- The job's
stepscontainstartedAtanddurationMsfor provision, checkout, task, collect and teardown. - The log prints
firstCommandAt, andX-Log-Stepsgives the command's own duration. - Time before provisioning includes scheduling and orchestration.
- A pending job with no
jobIdhas not received its container slot. - Provisioning includes credentials and network setup, so it is not a measurement of only the VM boot.

5. Measure a snapshot restore
Push the diagnostic to the default branch, and start it there. When a branch rule that requires a pull request covers the default branch, a manual run there is protected. So its restore job saves a snapshot when it passes.
Note
A manual run on another branch, with no pull request, saves no snapshot. Its restore job starts from the snapshot of the default branch, if one exists.
6. Start it on the default branch again
Start the diagnostic on the default branch again after the first run ends. The save runs in the background after the job. So if the second run finds no snapshot, start it once more.
7. Read the timing of the restore
src ci timing RUN_ID --job restore
- The part
Restore the snapshot (repository)is the restore. - The log of its step
Prepare restore fixturesaysThe fixture came from the snapshot. - The fixture is 16 MiB of random data, but the snapshot holds the whole container. These timings do not predict the restore time of a large
node_modules.
Done
You have the time of each startup part of a job: the queue, the provisioning, the checkout, the first command and a snapshot restore. Compare the individual parts before you change container sizes or concurrency.
Tip
A repository with a one-container limit runs these four jobs serially. Other CI jobs and factory jobs can also hold slots, so record the queue wait separately. The time to start a manual run is more than planning time: it also includes the API request and orchestration.
New jobs keep logs and step reports in the regional bucket of the run. Older jobs keep their original log location.
To read where the time of any run went, see Find out where your CI time goes.