V2 UI Reference — Debug Console

V2 UI Reference: Debug Console

The Debug Console is a modal dialog that runs the V2 pipeline in the foreground and streams the native php artisan rconfig:integration-v2-run stdout/stderr straight into the UI. It is the right tool for any time you need to watch a run instead of waiting for Run Insights to settle, or when you need a copy-pasteable log to attach to a support ticket.

The Debug Console is the same on every V2 driver.

It runs in the foreground

The Debug Console invokes the Artisan command synchronously on the rConfig server (not on the queue). For long Apply runs against large inventories, prefer the Detail page action bar’s Full Sync button — it dispatches via the queue and survives a page refresh. Use the Debug Console for diagnosing failures, not for routine production sync.

Opening the Console

Click Open Debug Console in the Detail page action bar. The button has a subtle shimmer to mark it as a power-user control.

The dialog opens with the current driver pre-selected. The title bar reads:

Integration Debug Console · Driver Display Name

Anatomy of the Dialog

Status Strip

The top of the dialog shows three live indicators:

• Status — idle, running, completed, or failed.
• Elapsed — wall-clock time since the run started.
• Chunks — number of stream poll responses received. Climbing chunk count without new output is a sign the run is mid-stage but not silent.

Beside the indicators sits a phase label with a pulsing dot — validating, extracting, canonicalizing, reconciling, deciding, applying. The phase is parsed from the live stream as the run progresses.

Mode & Debug Controls

Three toggles control what command will be run:

Control	Effect
Preview	Selects --mode=preview — the run stops after decide, no writes.
Apply	Selects --mode=apply — the run executes through apply, writing to devices.
Debug On / Off	Toggles --debug. With Debug On, every stage emits per-stage timings, full metrics and the chained exception trace (up to five previous exceptions) on failure.

Underneath, the command line that will be executed is rendered verbatim, e.g.:

php artisan rconfig:integration-v2-run <instance_id> --mode=preview --debug

This is the exact string you can also run from a terminal — handy when the dialog is failing for environmental reasons (queue worker missing, PHP CLI permission issues) and you want to bypass the UI.

Action Buttons

Button	What it does
Run Integration Debug	Kicks off the run. Disabled until the instance has a saved configuration; greyed for the duration of the run.
Copy Command	Copies the rendered CLI command to the clipboard.
Copy Output	Copies the entire output buffer captured so far.
? (Help)	Toggles the decision-reason crib sheet (see below).

Output Console

The bottom panel is a fixed-height monospace ScrollArea that renders streamed output line-by-line. While the run is active, a terminal-style cursor pulses on the trailing line. When idle the panel shows:

[idle] Choose a mode and click 'Run Integration Debug' to stream output here...

Lines are colour-tinted by source so stderr and per-stage banners stand out from regular stdout.

Decision-Reason Crib Sheet

Click ? to reveal a small reference panel with the decision reason codes the decide stage emits. The same codes appear in the Logs tab on every decide row, in decide.summary.top_decision_reason_codes in Run Insights, and on each Problem Devices row that requires review.

Reason code	Plain-English meaning	What happens on Apply
LINK_FOUND_BY_EXTERNAL_ID	Update an already linked device — the candidate’s upstream external ID matched an existing integration_device_links row from a previous run, so this is the same device.	The matched rConfig device is updated. No human review needed.
MEDIUM_MATCH_REQUIRES_REVIEW	One plausible existing device matched, so manual review is required — the candidate’s hostname + primary IP match a unique device, but not strongly enough to auto-link.	No write. Candidate appears in Problem Devices for an operator to confirm or reject.
AMBIGUOUS_MATCH_MULTIPLE_DEVICES	Multiple possible matches, so manual review is required — more than one rConfig device fits the candidate’s identity fingerprint, so V2 refuses to guess.	No write. Candidate appears in Problem Devices; operator picks the correct target.
NO_MATCH_CREATE_CANDIDATE	No match was found, so rConfig plans to create a new device on apply — the normal “this upstream host did not match any existing rConfig device, so create a new one” outcome.	A new rConfig device is created and linked to the upstream record.

LINK_FOUND_BY_EXTERNAL_ID and NO_MATCH_CREATE_CANDIDATE are the steady-state codes you want — they cover “update an existing device” and “create a new one” respectively. MEDIUM_MATCH_REQUIRES_REVIEW and AMBIGUOUS_MATCH_MULTIPLE_DEVICES always defer the decision to a human; chase them down in Problem Devices so they don’t accumulate.

Footer

A short footer line confirms what you’re watching:

Live output is streamed from the native Artisan command execution (stdout/stderr) while the run is active.

What the Streamed Output Looks Like

Output is the native Artisan output from IntegrationV2RunCommand. Roughly:

==> Run #214 starting (driver=statseeker, mode=preview, debug=on)
[validate_setup] connection ok, credentials ok            (elapsed 312 ms)
[extract] processed=128, pages=3, memory=24.3 MB          (elapsed 1.7 s)
[canonicalize] valid=124, invalid=4                       (elapsed 410 ms)
[reconcile] strong=110, medium=10, ambiguous=2, none=2    (elapsed 880 ms)
[decide] create=12, update=110, skip=4, conflict=2        (elapsed 220 ms)
==> preview_ready

When debug is on, each stage card prints its full metrics_json. When a stage fails, the chained exception list prints inline with file/line numbers — copy that block straight into a support ticket.

When to Use Each Run Mode

Goal	Recommended path
Confirm filters return the right hosts	Extract Preview in the action bar — much lighter than the console.
Walk the full pipeline once, watch it happen, see exactly where it stops	Debug Console, Preview, debug on.
Routine, scheduled production sync	Action-bar Full Sync (queued) or a Scheduled Task.
Reproduce a failure that only shows up under load	Debug Console, Apply, debug on, capture the output.
Capture a clean log to attach to a support ticket	Debug Console with Copy Output after the run.

The console run is a real run

A Debug Console run creates a real IntegrationRun row, persists stage logs, updates Problem Devices, and (in Apply mode) writes to devices. It is fully visible in Run Insights and Logs afterwards — it is not a parallel sandbox.

Closing the Dialog Mid-Run

Closing the modal stops the stream, not the run. The Artisan process keeps going on the server until it finishes; the resulting run will appear in Run Insights and Logs once complete. To watch from where you left off, re-open the console — it picks up the live stream of any run still in progress.

Where to Go Next

• See Extract Preview Tab for filter-only validation.
• See Run Insights Tab for the post-run dashboard.
• See Logs Tab for the per-stage history view, including chained exceptions captured during debug runs.

Asset Inventory

• Screenshot: PLACEHOLDER_v2_debug_console_idle.png — Debug Console open, no run yet, mode/debug toggles visible, command line rendered.
• Screenshot: PLACEHOLDER_v2_debug_console_running.png — Debug Console mid-run, status running, elapsed counter ticking, output area populated.
• Verification: confirm the title bar copy (Integration Debug Console · {driver display name}), idle placeholder text and footer copy match IntegrationDebugConsoleModal.vue at the V8.2.0 release tag.
• Verification: confirm the four reason codes in the crib sheet match what the Help panel renders in the released build.