Skip to content

Importer Options

Jump to bottom
JosephPilov-MSFT edited this page Sep 15, 2026 · 4 revisions

This page documents every SQL Nexus importer and how to control it — from the Options menu in the UI, from the persisted settings file, and from the command line with the /M switch.

For a general introduction to importing data, see How to use SQL Nexus.

Importer Options in the UI

When you click the Options button on the Import page, a dropdown menu appears with an Importers submenu. Each importer has configurable options that control its behavior during import. You can enable or disable individual importers and fine-tune their settings.

Available Importers and Their Options

Trace Event Importer (Managed)

Processes Extended Events files (*pssdiag*.xel, *LogScout*.xel) using the managed TraceEvent (XeLite) library built into SQL Nexus. This is the recommended and default importer for XEL files and it does not require RML Utilities/ReadTrace.exe to be installed.

It populates the same ReadTrace.* schema that ReadTrace produces (ReadTrace.tblBatches, tblStatements, tblUniqueBatches, tblUniqueStatements, tblConnections, tblInterestingEvents, tblTimeIntervals, tblBatchPartialAggs, tblStmtPartialAggs, tblMiscInfo, etc.), so all existing ReadTrace-based reports and queries work unchanged.

Note: .trc (SQL Trace) files are still processed by ReadTrace only. If your collection contains .trc files, enable the ReadTrace importer and install RML Utilities.

Option Default Description
Enabled ✅ On Enable or disable this importer
Drop existing ReadTrace tables ✅ On Drop and recreate trace-related tables before importing
Aggregation interval (seconds) 60 Time interval for aggregating trace events (not shown as a checkbox)
Import events using local server time (not UTC) ❌ Off Convert event timestamps from UTC to the local server time zone

ReadTrace (SQL XEL/TRC Files)

Processes trace files using the ReadTrace utility from RML Utilities. This importer requires ReadTrace.exe to be installed (see Installation and RML Utility). It is the only importer that can process .trc (SQL Trace) files. Note: Only one of Trace Event Importer (Managed) or ReadTrace can be enabled at a time — enabling one automatically disables the other.

Option Default Description
Enabled ❌ Off (can be enabled if ReadTrace.exe is found) Enable or disable this importer. Auto-disabled if ReadTrace.exe is not installed
Output trace files (.trc) by SPID to %TEMP%\RML ❌ Off Split trace output into per-SPID .trc files
Output RML files (.rml) to %TEMP%\RML ❌ Off Generate .rml replay files
Assume QUOTED_IDENTIFIER ON ✅ On Process queries assuming QUOTED_IDENTIFIER is enabled
Ignore events associated with PSSDIAG activity ✅ On Filter out trace events generated by PSSDIAG itself
Disable event requirement checks ❌ Off Skip validation of required trace events
Enable -T35 to support MARs ❌ Off Enable MARS (Multiple Active Result Sets) support during trace processing
Import events using local server time (not UTC) ❌ Off Convert event timestamps from UTC to local server time

ERRORLOG Importer

Imports SQL Server ERRORLOG files (*_ERRORLOG*, e.g. SERVERNAME_ERRORLOG, SERVERNAME_ERRORLOG.1) into the tbl_ERRORLOG table. Multi-line messages are folded into a single row, and the error number/state are extracted where present.

SQL LogScout can collect only the head and tail of an ERRORLOG larger than 1 GB. When the importer finds the collection marker showing that the middle was not captured, it inserts a row with Process set to INCOMPLETE and an explanatory message. This makes the missing interval visible in tbl_ERRORLOG instead of presenting the collected portions as a complete log.

Option Default Description
Enabled ✅ On Enable or disable this importer
Drop existing tables (ERRORLOG) ✅ On Drop and recreate ERRORLOG tables before importing

BLG Blaster (Perfmon/Sysmon BLG files)

Imports Windows Performance Monitor binary log files (*.BLG).

Option Default Description
Enabled ✅ On Enable or disable this importer
Drop existing tables (Perfmon) ✅ On Drop and recreate Perfmon tables before importing
Minimize Cmd window (Relog.exe) during import ❌ Off Minimize the relog.exe command window that appears during BLG processing
Relog DSN, ODBC driver selection, and encryption

The relog.exe Windows utility, which is used to import BLG files, requires an ODBC data source to write Perfmon data to SQL Server. SQL Nexus creates a user DSN named SQLNexusDSN once at the start of each Perfmon import and uses it for every .BLG file in that import. You do not need to create the DSN manually. Previous versions created a DSN named 'Nexus'

SQL Nexus discovers the SQL Server ODBC drivers installed on the local machine and selects them in this order:

  1. Drivers named ODBC Driver NN for SQL Server, ordered by numeric version from newest to oldest. This also allows future driver versions to be selected without a SQL Nexus code change.
  2. The legacy SQL Server driver, only as a last-resort fallback.

If installed-driver enumeration fails, SQL Nexus probes ODBC Driver 18 for SQL Server, then ODBC Driver 17 for SQL Server, and finally the legacy SQL Server driver. The application log records the driver used or the fallback-probing attempt.

The DSN receives the same Encrypt connection and Trust server certificate choices used by the SQL Nexus application connection. Modern Microsoft ODBC drivers honor these settings, allowing relog.exe to use an encrypted SQL Server connection. The legacy SQL Server driver may not enforce the requested encryption; SQL Nexus logs a warning when encryption is requested but that driver must be used.

If SQL Nexus cannot create SQLNexusDSN with any available SQL Server ODBC driver, the Perfmon import stops and reports the failure instead of running relog.exe and silently importing zero rows. SQL Nexus does not place credentials in the logged relog.exe command line.

Import Linux Performance Files (.perf)

Imports Linux performance data files (*.perf) collected from SQL Server on Linux.

Option Default Description
Enabled ❌ Off Enable or disable this importer. Disabled by default — enable manually if you have Linux perf data
Import to SQL (Linux Perf) ✅ On Import the parsed performance data into SQL Server tables
Drop existing tables (Linux Perf) ✅ On Drop and recreate Linux performance tables before importing

Rowset Importer

Imports text-based rowset output files (*.OUT, *.TXT) generated by SQLDiag or SQL LogScout.

Option Default Description
Enabled ✅ On Enable or disable this importer
Drop existing tables ❌ Off Drop and recreate rowset tables before importing

Import SQLDiag / AlwaysOn / System Health XEL

Imports XEL files auto-generated by SQL Server for Failover Cluster Instances (*_SQLDIAG*.xel), Always On Availability Groups (*AlwaysOn_health*.xel), and system health sessions (*system_health*.xel).

Option Default Description
Enabled ❌ Off Enable or disable this importer. Disabled by default — enable manually if you need to analyze these XEL files
Drop existing tables ✅ On Drop and recreate the corresponding tables before importing

Additional Import Options

These options appear at the top level of the Options menu (outside the Importers submenu):

Option Default Description
Drop DB before importing ❌ Off Drop and recreate the entire SQL Nexus database before starting import. Use this for a clean start
Save import options ❌ Off Persist your importer option choices so they are restored the next time you open the Import page (see Saving Import Options below)
Use default options N/A Resets all importer options to their defaults and clears any saved preferences

Saving Import Options

By default, SQL Nexus does not remember your importer option changes between sessions — each time you open the Import page, all importers revert to their default settings.

To persist your choices, check Save import options in the Options menu. Once enabled:

  • Every time you toggle an importer option, the change is automatically saved.
  • When you reopen the Import page, your saved preferences are restored.
  • Clicking Use default options clears all saved preferences and resets everything to defaults.

Where Settings Are Stored

SQL Nexus uses the standard .NET user settings mechanism to persist preferences. The settings are stored in an XML configuration file located under your Windows user profile:

%LOCALAPPDATA%\Microsoft\sqlnexus.exe_Url_<hash>\<version>\user.config

The user.config file contains all user-scoped settings — not just the importer options. Here is the full list of settings saved in this file:

Setting Type Default Description
ShowMainMenu bool True Show or hide the main menu bar
ShowStandardToolbar bool True Show or hide the standard toolbar
ShowDataCollectionToolbar bool False Show or hide the data collection toolbar
ShowReportToolbar bool True Show or hide the report toolbar
ShowReportNavigator bool False Show or hide the report navigator panel
ShowReportTabs bool False Show or hide report tabs
QueryTimeout int 6000 SQL query timeout in seconds for report queries
ImportPath string (empty) Last used import folder path
LastUsedServerName string (empty) Last SQL Server instance connected to
EncryptConnection bool True Encrypt the SQL Server connection, including sqlcmd post-processing (-N)
TrustCertificate bool False Trust the server certificate without validation, including during sqlcmd post-processing (-C)
Theme string Default UI and report theme (Default, Aquatic, or Desert)
ImporterOptions string <root></root> XML blob containing saved importer option choices (see below)

ImporterOptions format

When Save import options is enabled, the ImporterOptions setting stores all importer choices as an XML string:

<setting name="ImporterOptions" serializeAs="String">
  <value>
    &lt;root&gt;
      &lt;item key='SaveImportOptions' value='True'/&gt;
      &lt;item key='Trace Event Importer (Managed).Enabled' value='True'/&gt;
      &lt;item key='Trace Event Importer (Managed).Drop existing ReadTrace tables' value='True'/&gt;
      &lt;item key='ERRORLOG Importer.Enabled' value='True'/&gt;
      &lt;item key='BLG Blaster (Perfmon/Sysmon BLG files).Enabled' value='True'/&gt;
      &lt;item key='DropDbBeforeImporting' value='False'/&gt;
      &lt;item key='SQLDiagAlwaysOnXEL.Enabled' value='False'/&gt;
      &lt;item key='SQLDiagAlwaysOnXEL.DropExistingTables' value='True'/&gt;
    &lt;/root&gt;
  </value>
</setting>

Each importer option uses the format ImporterName.OptionName as the key. You do not need to edit this file manually — use the Options menu in the Import page to manage your preferences.

Selecting importers from the command line (/M)

The /M switch lets you control exactly which importers run for a single command-line import, without changing any saved UI settings. It is useful in automation when you only want a subset of the data (for example, import Perfmon and ERRORLOG but skip the expensive XEvent trace processing).

For the full command-line reference, see How to use SQL Nexus.

Tokens

Token Importer
TraceEventImporter (aliases: Trace, TraceImp, TraceImporter) Trace Event Importer (Managed) — XEL files
ReadTrace ReadTrace (SQL XEL/TRC Files) — requires RML Utilities
Perfmon BLG Blaster (Perfmon/Sysmon BLG files)
Linux Import Linux Performance Files (.perf)
Errorlog ERRORLOG Importer
CustomXEL SQLDiag / AlwaysOn / System Health XEL importer
All Every wired built-in importer above

Tokens are case-insensitive.

Syntax

Form Meaning
/M<token>[+<token>...] Additive — run only the listed importers
/MAll Run every wired built-in importer
/MAll-<token>[-<token>...] Subtractive — run everything except the listed importers

+ (add) and - (subtract from All) cannot be combined in a single /M value, and unknown tokens are rejected with an error.

Rules and behavior

  • The Rowset Importer always runs, regardless of /M. It populates the core tbl_* tables that every other stage and report depends on. The same applies to raw file import, post-import processing, PerfStats analysis, runtime counting, and report enumeration.
  • The two XEvent trace importers are one logical capability. ReadTrace and TraceEventImporter write to the same ReadTrace.* schema and are mutually exclusive. If both are selected, the managed Trace Event Importer wins. Subtracting either one (or the generic Trace token) with All-... suppresses both, so no XEvent trace data is imported.
  • Automatic fallback. If you request the managed importer but its assembly is not present, SQL Nexus falls back to ReadTrace (and vice versa) so trace data is still imported. If neither is available, a warning is logged.
  • /M only governs the explicitly-wired built-in importers. Unknown or drop-in assemblies are never enabled by /M.
  • /M does not modify user.config. It overrides your saved UI importer options for that run only.
  • /M selects importers only — you still need /I to specify what to import.

Exit codes

Code Meaning
0 Normal completion
-1 User cancelled
2 Unhandled exception
3 Import incomplete — an importer requested via /M was missing or imported no data

Exit code 3 matters for automation: the core load may have succeeded, but data you explicitly asked for did not arrive, so the run must not be treated as fully successful.

/M examples

:: Only Perfmon and ERRORLOG data
sqlnexus.exe /S"." /E /D"sqlnexus" /I"C:\output" /MPerfmon+Errorlog /X /Q

:: Everything
sqlnexus.exe /S"." /E /D"sqlnexus" /I"C:\output" /MAll /X /Q

:: Everything except XEvent traces and Perfmon
sqlnexus.exe /S"." /E /D"sqlnexus" /I"C:\output" /MAll-Trace-Perfmon /X /Q

:: Force the classic ReadTrace importer (requires RML Utilities)
sqlnexus.exe /S"." /E /D"sqlnexus" /I"C:\output" /MReadTrace+Perfmon /X /Q

:: Import only the ERRORLOG and Perfmon data into a brand-new database and exit
sqlnexus.exe /S"." /E /D"sqlnexus_errorlog" /I"C:\data_collection\output" /N /MErrorlog+Perfmon /X /Q

Clone this wiki locally