Migration guide to version 14
Published 28 March 2024
Version 14 of Redgate Monitor has some breaking changes. This means that some manual changes are needed when upgrading. The Redgate Monitor team was committed to making the upgrade process as seamless as reasonably possible.
Deprecated platforms
Redgate Monitor v. 14 no longer supports the following platforms:
- installing Redgate Monitor on Windows Server 2012 R2 or any earlier version (monitoring is still supported). See Migrating Redgate Monitor.
- monitoring Postgres 10.
- monitoring unpatched versions of SQL Server 2008 R2 and 2012 that don't support extended events properly:
- SQL Server 2008 R2 earlier than SP2 CU12
- SQL Server 2012 earlier than SP1 CU6
Configuration files and query search data location
The location of configuration files was changed from %ProgramData%\Red Gate\SQL Monitor
to %ProgramData%\Red Gate\Redgate Monitor
.
This includes data used by the query search stored by default in the %ProgramData%\Red Gate\SQL Monitor\SearchEngine
.
The installer copies the configuration files and moves the query search data automatically.
In case it fails, rename the SQL Monitor
folder to Redgate Monitor
and ensure that the user running the Redgate Monitor Windows services has read-write access to the folder.
Once Redgate Monitor v. 14 runs successfully, it's safe to remove the old SQL Monitor folder - though backing it up first is recommended.
From version 14.0.3 the SQL Monitor
folder is renamed to SQL Monitor - backup
. If you have stored the certificate used when enabling https in this location you should update the path in the webserver.kestrel.config file to the new file path using Redgate Monitor
Any other configuration files will also be moved and if there are references that were manually made to the SQL Monitor
folder location they will need to be updated to Redgate Monitor
.
Default installation location
The default installation location was changed from %ProgramFiles%\Red Gate\SQL Monitor
to %ProgramFiles%\Red Gate\Redgate Monitor
. The installer will offer the new location if the default location was used before.
If Redgate Monitor was installed into IIS with the default installation location, then IIS must be configured to use the updated install location as described on the final step of the installer.
Logs location
The location of logs was changed from %ProgramData%\Red Gate\Logs\SQL Monitor
to %ProgramData%\Red Gate\Logs\Redgate Monitor
. Old logs are not migrated to the new location and can be safely deleted at will.
Windows service display names
The Windows service display names were changed from SQL Monitor Base Monitor
to Redgate Monitor Base Monitor
, and from SQL Monitor Web Service
to Redgate Monitor Web Service
. The underlying names of the services remain the same.
This rename will be performed automatically during the installation, but if any automation relies on the service's display name, it must be updated.
PowerShell module name and default command prefix
- The name of the PowerShell module changes from
RedgateSQM
toRedgateMonitor
. - The default command prefix changes from
SqlMonitor
toRedgateMonitor
.
As described in PowerShell API, to integrate with the PowerShell API, the PowerShell module needs to be imported first. Up to version 13, it was done with Import-Module .\RedgateSQM\
. From version 14, it is Import-Module .\RedgateMonitor\
.
The change of the default command prefix means that the name of every cmdlet in the PowerShell module has changed. For example, the Connect-SqlMonitor
, Get-SqlMonitorMonitoredObject
and Add-SqlMonitorAnnotation
cmdlets are now called Connect-RedgateMonitor
, Get-RegateMonitorMonitoredObject
and Add-RedgateMonitorAnnotation
.
There are two simple approaches you can take to updating existing scripts that use the PowerShell module:
- Rename the cmdlets in your scripts by replacing occurrences of
-SqlMonitor
with-RedgateMonitor
. - When importing the PowerShell module, explicitly override the new default command prefix with the previous prefix, using the
-Prefix
parameter, like this:Import-Module .\RedgateMonitor -Prefix SqlMonitor
Note that going forward, the documentation and examples will refer to the new default command prefix of RedgateMonitor
, so we strongly advise performing the one-off migration.
Updated alert names
The names of some alerts have been updated for consistency across Redgate Monitor. Additionally, the Deadlock (Extended event) alert has superseded the legacy mechanism of reading from the error log with trace flags 1204 and 1222 enabled; consequently, the alert is now just called Deadlock, and the previous alert has been removed. Any scripts handling alerts, for example in mail clients or recipients of webhooks that depend on alert names should be updated. Alert types present in PowerShell scripts should also be updated as summarized below. Consult the List of alerts for more details on specific alerts.
Alert name v13 | Alert name v14 |
---|---|
Machine unreachable | Host unreachable |
Internal SQL Monitor error (machine) | Internal Redgate Monitor error (host) |
Internal SQL Monitor error (SQL Server) | Internal Redgate Monitor error (instance) |
Monitoring error (host machine data collection) | Monitoring error (host data collection) |
Monitoring error (SQL Server data collection) | Monitoring error (instance data collection) |
Monitoring stopped (host machine credentials) | Monitoring stopped (host credentials) |
Monitoring stopped (Instance credentials) | Monitoring stopped (instance credentials) |
Deadlock (extended event) | Deadlock |
Deadlock | Deadlock (deprecated) |
Job cancelled | Job canceled |
Job failure | Job failing |
SQL Server log entry | Log entry |
PowerShell module alert types
The PowerShell module's alert types have been updated as follows. The changes will need to be reflected in scripts that use the -AlertType
parameter to cmdlets such as Get-RedgateMonitorAlertSettings
.
PowerShell Alert type name up to v. 13 | Alert type name in v. 14 and beyond |
---|---|
| ErrorLogEntry |
| LogEntry |
| removed, use Deadlock |
| Deadlock |
| JobCanceled |
| JobFailure |
| HostUnreachable |
| InstanceUnreachable |
| BlockingProcess |
| LongRunningQuery |
| MonitoringStoppedHostCredentials |
| MonitoringStoppedInstanceCredentials |
| MonitoringStoppedHostDataCollection |
| MonitoringStoppedInstanceDataCollection |
| InternalMonitorErrorForHost |
| InternalMonitorErrorForInstance |
| LowDiskSpace |
| LowMemorySpace |
PowerShell module deprecated cmdlets removal
Deprecated cmdlets that have names in plural were removed: Get-SqlMonitorTags
, Add-SqlMonitorTags
, Remove-SqlMonitorTags
, Get-SqlMonitorSubGroups
, Get-SqlMonitorMainGroups
, Update-SqlMonitorAlertSettingsComments
.
Use corresponding cmdlets with a singular name. For example: Get-RedgateMonitorTag
Deprecated cmdlets for retrieving specific monitored server types have been removed: Get-SqlMonitorCluster
, Get-SqlMonitorLinuxMachine
, Get-SqlMonitorAzureSqlServer
, Get-SqlMonitorMachine
, Get-SqlMonitorAmazonRdsSqlServer
, and Get-SqlMonitorAzureManagedInstance
.
Instead use: Get-RedgateMonitorMonitoredObject
with the -Type
parameter.
PowerShell module deprecated cmdlet parameter removal
The Add-RedgateMonitorMonitoredObject
cmdlet now only has a single -MonitoredObject
parameter. This parameter no longer accepts a simple hostname string.
Instead, you must supply one or more objects as returned by the New-...
cmdlets (eg. New-RedgateMonitorWindowsHost
, New-RedgateMonitorPostgreSql
, etc.)