Other

Write-sqmSetupEvent

Internal, side-effect-free helper that appends one structured JSON-Lines event to a file during a setup run. New-sqmSetupReport replays the resulting stream as an animated HTML timeline. A no-op whenever -Path is empty, so callers can invoke it unconditionally without checking whether report generation is enabled.

Module: sqmSQLTool

Requires: None

ShouldProcess: No

Output: None (void)

Execution Flow

The entire function body is wrapped in a single try/catch that only writes to Write-Verbose on failure — a logging/serialization error here must never break the actual SQL Server installation it's instrumenting. Because ConvertTo-Json -Compress never emits embedded newlines, each Add-Content call appends exactly one valid JSON object per line, keeping the file a well-formed JSON-Lines stream throughout the run.

Parameters

Parameter	Type	Required	Description
-Path	String	Optional	Target JSON-Lines file. Empty/`$null` → no-op (report generation is opt-in).
-Phase	String	Required	Coarse pipeline station: `copy`, `preinstall`, `dirs`, `install`, `components`, `drivers`, `postinstall`, `alwayson`.
-Step	String	Optional	Stable step identifier within the phase, e.g. `copy-sources`, `hadr`, `node-restart`, `listener`.
-State	String	Optional	`start`, `progress` (default), `done`, `warn`, or `error`.
-Title	String	Optional	Short human-readable label shown in the report.
-Detail	String	Optional	Optional detail line, e.g. instance name or path.
-Pct	Int	Optional	Progress percentage (0–100); `-1` = not applicable. Default: -1.
-Node	String	Optional	Node/instance this event relates to (used for the AlwaysOn visuals).
-Viz	String	Optional	Front-end visualization hint: `flow-arrows`, `disk-format`, `gears`, `bar`, `node-restart`, `node-fetch`, `data-replicate`, `listener`, `check`. Defaults to a sensible value per `-Phase` when omitted.

Return Value

No return value — the function's only effect is appending one line to the file at -Path (or doing nothing if -Path is empty).

Examples

Example 1 — Mark the start of a phase

Write-sqmSetupEvent -Path $eventPath -Phase 'install' -State 'start' -Title 'Installing SQL Server Engine'

Example 2 — Report progress with a percentage

Write-sqmSetupEvent -Path $eventPath -Phase 'copy' -Step 'copy-sources' -Pct 45

Example 3 — Flag a warning on a specific node

Write-sqmSetupEvent -Path $eventPath -Phase 'alwayson' -State 'warn' -Node 'SQL02' -Title 'Seeding slower than expected'

Example 4 — Safe to call unconditionally when reporting is off

$eventPath = if ($ProgressReport) { $reportEventFile } else { $null }
Write-sqmSetupEvent -Path $eventPath -Phase 'postinstall' -State 'done'  # no-op if $eventPath is $null

⬆ Index

All Commands