jackin diagnostics

Synopsis

jackin diagnostics summary <RUN_ID_OR_PATH> [--top <N>]
jackin diagnostics compare <RUN_ID_OR_PATH> <RUN_ID_OR_PATH>... [--top <N>] [--baseline fastest|first] [--label <LABEL>]... [--format text|json] [--output <PATH>]

jackin diagnostics reads run JSONL artifacts that jackin' already wrote under ~/.jackin/data/diagnostics/runs/. It does not mutate host repositories, Docker state, credentials, or agent config.

Subcommands

Subcommand	Description
`summary`	Print the slowest launch stages, nested timings, launch-plan decisions, Docker build steps, and cache decisions for one run.
`compare`	Compare stage timings, nested timings, selected launch plans, build-context sizes, Docker build steps, and cache decisions across two or more runs.

`jackin diagnostics summary`

jackin diagnostics summary jk-run-046bca
jackin diagnostics summary ~/.jackin/data/diagnostics/runs/jk-run-046bca.jsonl --top 20

The argument can be a run ID such as jk-run-046bca or a direct path to a .jsonl artifact. The command prints:

run ID, file path, event count, observed timeline span, and startup span through the first hardline stage event when present;
the slowest broad launch stages from stage_done events;
the slowest nested timings from timing_done events;
skipped nested timings such as empty credential/env graphs;
explicit blocking workspace freshness timings such as workspace/git_pull_on_entry when git_pull_on_entry is enabled;
selected and rejected launch-plan decisions such as AttachExisting, StartStopped, CreateFromValidImage, or BuildAndCreate;
build-context source, file, and byte counts for rebuild runs;
cache hit/miss counts and individual cache decisions such as image_cache_hit or image_cache_miss, including derived-image invalidation reasons like hooks_hash_changed or selected_agent_install_changed and background refresh events such as image_refresh_background or selected_image_refresh_started;
parsed Docker build steps when a build log was available.

Use this after jackin --debug to compare cold, warm, and restart launches without hand-parsing JSONL.

`jackin diagnostics compare`

jackin diagnostics compare jk-run-cold jk-run-warm jk-run-restart --top 15
jackin diagnostics compare jk-run-cold jk-run-warm jk-run-restart --baseline first
jackin diagnostics compare jk-run-cold jk-run-warm jk-run-restart --format json --output ./launch-timings.json
jackin diagnostics compare jk-run-a jk-run-b --label cold-before --label warm-after --format json
jackin diagnostics compare ~/.jackin/data/diagnostics/runs/jk-run-a.jsonl ~/.jackin/data/diagnostics/runs/jk-run-b.jsonl

compare accepts two or more run IDs or direct .jsonl paths. It prints each run's startup span with a delta and slowdown or speedup ratio against the fastest supplied run by default; pass --baseline first when the first argument is the cold or pre-change run and every following run should be compared to that baseline. Repeat --label once per run to replace run IDs or file stems with stable report names such as cold-before, warm-after, and restart-after. It also prints observed timeline, event count, cache hit/miss count, then ranks broad stages and nested timings by the slowest duration observed across all supplied runs. It compares skipped timings, selected launch plans, build-context source plus maximum bytes/file counts, slowest parsed Docker build steps, and cache decisions per run, so cold/warm/restart runs show whether attach/start/create/build plans, credential skips, published-base vs workspace context creation, build-step work, or image rebuilding stayed in the foreground path. Use it to prove whether a launch change moved work out of the foreground path instead of only improving one isolated run.

Pass --format json for machine-readable comparison rows with startup/timeline spans, numeric startup delta/saved/ratio fields, cache counts, selected launch plan, all launch-plan events, all build-source and base-image pull-policy decisions, all build-context snapshots, build-context maxima, full broad-stage and nested-timing duration maps, slowest stage/timing, slowest Docker build step, all parsed Docker build steps, the first cache decision, all cache decisions, and skipped timing rows. startup_saved_ms is positive when the row is faster than the selected baseline and negative when it is slower. The JSON root also names the fastest and slowest startup run, startup spread in milliseconds, selected-plan counts, cache-decision counts, and the slowest stage/timing/build-step bottlenecks across all runs. Add --output <PATH> to write that JSON artifact to an explicit operator-selected path instead of stdout; --output requires --format json and does not write anywhere else.

Options

Option	Description
`--top <N>`	Number of rows to print per timing/build/comparison section. Defaults to `10`.
`--baseline <MODE>`	Startup delta baseline. `fastest` compares every run to the fastest supplied startup span. `first` compares every run to the first supplied run, which is useful for cold-before / warm-after timing reports.
`--label <LABEL>`	Display label for one supplied run. Repeat once per run when used; labels appear in text tables and JSON rows.
`--format <FORMAT>`	Output format for `compare`. `text` prints human-readable tables. `json` emits machine-readable cold/warm/restart comparison rows. Defaults to `text`.
`--output <PATH>`	Write `compare --format json` output to an explicit artifact path instead of stdout. Requires `--format json`.

Output

Example shape:

Run: jk-run-046bca
File: /Users/alex/.jackin/data/diagnostics/runs/jk-run-046bca.jsonl
Events: 120
Timeline: 108.4s
Startup: 108.3s
Cache: 1 hit(s), 0 miss(es)

Stages
       55.5s  credentials
       15.5s  derived image

Timings
       34.0s  credentials/operator_env

Docker Build Steps
       76.5s  ran    #46 exporting to image

Launch Plans
  selected AttachExisting         current_role_container_running      jk-demo                      running

Cache Decisions
  image_cache_hit  derived image  reusing derived image jk_the-architect (recipe_hash_match)

The summary is derived from the artifact only. If a run predates a newer diagnostics event, that section may be empty.