Documentation / Query Benchmark / Tips & Troubleshooting

Tips & Troubleshooting — Query Benchmark

Requirements

  • Windows 10/11 or Windows Server 2016+
  • SQL Server 2016+ recommended (session wait stats / grant columns); earlier versions may omit some metrics
  • VIEW SERVER STATE (or equivalent) for DMVs; DBCC rights for warm/cold cache; catalog tips may need VIEW DATABASE STATE

Troubleshooting

  • App won’t start when copying only the EXE — Use the published single-file build that embeds native libraries (IncludeNativeLibrariesForSelfExtract).
  • Connection picker does nothing — Add the server in the left Connections sidebar first, then select it on the main page (auto-connect). There is no separate Connect button.
  • Grant memory / DOP show 0 — These come from sys.dm_exec_query_stats (not the plan XML) and need VIEW SERVER STATE; very trivial plans may report 0 grant / DOP 0 or 1.
  • Logical reads don’t match SSMS — Reads come from SET STATISTICS IO on the measured batch only. If your script uses GO, leading setup batches are excluded automatically; put the query you want measured in the last batch.
  • Throughput looks low — Throughput is successful executions ÷ total wall-clock time (includes think time, warm-up gaps, and UI overhead between iterations), not a server-side counter.
  • Cache DBCC options fail — Missing elevated rights; leave Cache & Stats unchecked on shared servers.
  • Waits empty — Pre-2016 instance or missing permission on dm_exec_session_wait_stats.
  • Entra / Azure SQL — Encryption is forced to Mandatory; use Trust certificate carefully and prefer Entra Default or MFA when interactive.
  • Auth dropdown looks wrong after upgrade — Restart the app; saved profiles store the auth tag (Windows, SqlAuth, Entra*).
  • Live charts empty — Charts need at least one sample after the run. Keep Live resource metrics checked; use ≥5–8 iterations or a timed duration so the monitor can poll (every ~0.5s). Very short runs used to leave the panels blank.
  • Parameters not substituting — Names must match SQL (@Name); use Detect @params; for Range set Min/Max; for Csv provide inline values or a file path.
  • CLI regression always fails — Compare like-for-like (same iterations/users/cache). Prefer --fail-on-p95 for load tests; avg is noisier under concurrency. See CI/CD Pipeline.
  • Tuning Assistant empty / few tips — Run a benchmark first; enable Collect actual plan; ensure the connection is still open for catalog checks. See Query Tuning Assistant.
  • Save Scenario / Load / Export missing — Use the File menu (scenarios are named in a dialog; Load is a submenu of saved names).

CLI quick reference

DBLenseQueryBenchmark.exe --run [options]

  --server / -S, --database / -d, --user / -U, --password / -P
  --sql | --sql-file | --scenario <path.json>
  --users <n>  --iterations <n>  --duration <sec>
  --out <report.json|html|md|xls|pdf|xml>
  --out-junit <results.junit.xml>
  --baseline <prior-report.json>
  --fail-if-regression <pct>   (alias: --fail-on-regression)
  --fail-on-p95                gate on P95 instead of average

Exit codes: 0 ok · 1 error · 2 regression · 3 execution errors

Full CI outputs and pipeline examples: CI/CD Pipeline. In-app snippets: Help → CI/CD Pipeline Integration….

Automated UI walkthrough

Developers can re-record the product walkthrough (screen capture + screenshots for this documentation) after code changes:

cd DBLenseQueryBenchmark\tests\UiWalkthrough
powershell -File .\run-walkthrough.ps1

# Or watch *.cs / *.xaml and re-run automatically:
powershell -File .\watch-and-retest.ps1

Outputs: %USERPROFILE%\Videos\DBLenseQueryBenchmark-functionality-test.avi (and demo MP4 under Website/public/videos/ when ffmpeg is available), plus qb-*.png screenshots in Website/public/img/docs/.