Annotations
Published 14 February 2023
The annotations API can be used to add annotations to the top graph (timeline) for SQL Server instances, for example to record the time of a deployment.
Add-Annotation
You can add an annotation with a command similar to this:
Add-SqlMonitorAnnotation -Target $instance -Description "Deployment" -UtcDate Get-Date
Parameters:
| Name | Type | Mandatory | Description |
|---|---|---|---|
| Target | MonitoredObject | Yes | The SQL Server instance to target the annotation at. Since SQL Monitor ver. 12.1.20 cloud servers are also supported. |
| Description | string | No | A textual description; will form the title of the annotation unless Source is specified, where it will form an additional line of information |
| UtcDate | DateTime | Yes | The time in UTC to attach the annotation |
| Url | string | No | A URL to navigate the user to if the annotation is clicked |
| Source | string | No | The source of the annotation, such as Error or SQL Update |
| DatabaseName | string | No | Unused for now |
| SpecificInfo | string | No | Customises different types of annotations |
Valid Sources:
| Name | Description | ||
|---|---|---|---|
| Deployment | For annotating deployments to the SQL Server. Use SpecificInfo to specify what was deployed. |
|
|
| Error | For annotating errors. Use SpecificInfo to specify error. |
|
|
| Permissions Change | For annotating permissions changing on a SQL Server. |
|
|
| Configuration Change | For annotating configuration changes. Use SpecificInfo to indicate what configuration was configured. |
|
|
| SQL Update | For annotating SQL Updates. Use SpecificInfo to provide the version number updated. |
|
|
Get-Annotation
Get details about an annotation on a SQL Server instance at a given time.
$annotation = Get-SqlMonitorAnnotation -Target $instance -UtcDate $dateRemove-Annotation
Removes an annotation from a SQL Server instance at a given time.
Remove-SqlMonitorAnnotation -Target $instance -UtcDate $dateUpdate-Annotation
Updates an annotation on a SQL Server instance at a given time by overwriting the annotation with the newly provided details.
Takes the same arguments as Add-Annotation.
