V2 UI Reference — Logs Tab

V2 UI Reference: Logs Tab

The Logs tab is the long-form history view for a V2 integration instance. While Run Insights shows only the latest run, Logs lists every stage of every run — Sync Preview and Full Sync — with the full error payload and metrics for each one.

This tab is identical across all V2 drivers.

When to reach for Logs

Three reasons: (1) you need to compare the same stage across multiple runs, (2) Run Insights shows a failed stage and you need the full exception trace, or (3) you’re investigating a problem that no longer reproduces and need the historical state.

What’s in the Table

Each row is one integration_run_stages record — i.e. one stage of one run. A typical successful Full Sync produces six rows (validate_setup, extract, canonicalize, reconcile, decide, apply); a Sync Preview produces five (no apply).

Column	What it shows
Run	#<run_id> · <mode> / <run_status>. Mode is preview or apply. Run status is the run-level status as of the last refresh.
Stage	Stage badge — colour-coded: validate_setup is info, the pipeline core (extract/canonicalize/reconcile/decide) is primary, apply and preview_results are secondary.
Status	Stage badge — completed/preview_ready are green, running/queued are amber, failed/error are red.
Attempt	Attempt counter. 1 is the normal case; anything higher means the stage was retried (queued runs auto-retry within their job’s retry budget).
Started	Timestamp the stage began.
Finished	Timestamp the stage finished. Empty for running rows.
Details	Short preview of error_summary plus the top two metric values, with a View full hover button for the complete payload.

The Details Hover Card

The Details column is the high-value part of the tab. The cell shows:

• The first 120 characters of error_summary (when present), and
• The first two metrics as key: value pairs — usually enough to know if a stage processed the right number of records.

Click View full to expand the hover card. The card contains:

• Full error summary — the unabridged one-line message.
• Metrics breakdown — every key in metrics_json rendered as a key/value grid (object values pretty-printed).
• Raw record details — the full error_payload and metrics_json in a collapsible <details> element. When the run was launched with --debug (or via the Debug Console with debug on), this includes up to five chained previous exceptions with their stack traces.
• Copy button — one-click copy of the full details JSON for sharing in tickets.

Decision Reason Codes

Every decide row in the Logs table carries one or more decision reason codes in its metrics block, and the same codes show up aggregated in decide.summary.top_decision_reason_codes on the Run Insights stage card. They are how V2 explains, per candidate, why it landed on create, update, skip or conflict.

The four most common are:

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 link from a previous run.	The matched rConfig device is updated. No human review needed.
MEDIUM_MATCH_REQUIRES_REVIEW	One plausible existing device matched, so manual review is required — 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.	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 is new, create it” outcome.	A new rConfig device is created and linked to the upstream record.

For the full crib sheet (and the ? panel that surfaces it inside the Debug Console at run time), see the Debug Console — Decision-Reason Crib Sheet.

Status Badge Reference

Status	Tone	Meaning
completed	Success	Stage finished without throwing.
preview_ready	Success	Sync Preview reached decide and is waiting for an Apply decision.
running	Warning	Stage is currently executing.
queued	Warning	Stage has been dispatched to the queue and is waiting for a worker.
failed	Danger	Stage threw and the run was marked failed at this point.
error	Danger	Soft error variant — the stage produced an error payload but the run continued.

Common Investigation Patterns

”The run failed but I don’t know why”

1. Find the failed run by run_id.
2. Locate the row whose Status badge is red — there will be exactly one per failed run.
3. Click View full. The error summary tells you which subsystem failed; the chained exceptions in the <details> block tell you the actual cause.
4. If the chained exceptions are missing, re-run with the Debug Console using debug on, then check Logs again.

”My counts are different from last week”

1. Find a known-good run from the prior week.
2. Compare its extract and canonicalize rows against today’s run.
3. Differences in processed, valid, invalid between the two reveal upstream changes (records added, removed, or now failing canonical validation).

”A stage is stuck in running”

1. Confirm queue workers are up (php artisan horizon:status or your worker manager).
2. If the worker is up but the row is stale, the underlying job may have died. Re-run from the action bar — the new run will create new stage rows; the orphan row will eventually time out.

Purge Logs

The Purge Logs button in the top-right deletes all integration_run_stages for this instance after a confirmation dialog:

Purge integration logs? This will permanently remove all stage log entries.

Use this carefully:

• The action is immediate and irreversible — no soft-delete, no per-run filter.
• It removes the log rows, not the runs themselves; the IntegrationRun rows and their summary stats remain intact, so Run Insights still works for the latest run.
• It does not touch integration_canonical_candidates, integration_reconciliation_results, integration_sync_decisions, integration_conflicts or integration_device_links — only the per-stage log records.

A common operating pattern is to purge after a successful migration / Apply, once you are sure no investigation is pending, to keep the table small.

Pagination & Refresh

• Refresh icon (top right) — re-fetches the latest log page.
• Previous / Next — page through the history. Newest runs appear first.

Where to Go Next

• See Run Insights Tab for the latest-run dashboard view of the same data.
• See Problem Devices Tab for the per-device side of failures.
• See Debug Console to capture detailed logs for a fresh run.

Asset Inventory

• Screenshot: PLACEHOLDER_v2_logs_tab.png — Logs tab with at least two runs visible, one with a failed stage row in red.
• Screenshot: PLACEHOLDER_v2_logs_details_card.png — expanded Details hover card with full error summary, metrics grid and copy button.
• Verification: confirm the column order (Run, Stage, Status, Attempt, Started, Finished, Details) matches IntegrationLogsTab.vue at the V8.2.0 release tag.
• Verification: confirm the Purge Logs confirmation copy is unchanged in the released build.