Release annotations for Application Insights
Annotations show where you deployed a new build, or other significant events. Annotations make it easy to see whether your changes had any effect on your application's performance. They can be automatically created by the Azure Pipelines build system. You can also create annotations to flag any event you like by creating them from PowerShell.
Release annotations with Azure Pipelines build
Release annotations are a feature of the cloud-based Azure Pipelines service of Azure DevOps.
If all the following criteria are met, the deployment task creates the release annotation automatically:
The resource you're deploying to is linked to Application Insights (via the
APPINSIGHTS_INSTRUMENTATIONKEY
app setting).The Application Insights resource is in the same subscription as the resource you're deploying to.
You're using one of the following Azure DevOps pipeline tasks:
Task code Task name Versions AzureAppServiceSettings Azure App Service Settings Any AzureRmWebAppDeployment Azure App Service deploy V3 and above AzureFunctionApp Azure Functions Any AzureFunctionAppContainer Azure Functions for container Any AzureWebAppContainer Azure Web App for Containers Any AzureWebApp Azure Web App Any
Note
If you’re still using the Application Insights annotation deployment task, you should delete it.
Configure release annotations
If you can't use one the deployment tasks in the previous section, then you need to add an inline script task in your deployment pipeline.
Specify the relevant Azure subscription. Change the Script Type to PowerShell and Script Location to Inline.
Add the PowerShell script from step 2 in the next section to Inline Script.
Add the arguments below, replacing the angle-bracketed placeholders with your values to Script Arguments. The -releaseProperties are optional.
-aiResourceId "<aiResourceId>" ` -releaseName "<releaseName>" ` -releaseProperties @{"ReleaseDescription"="<a description>"; "TriggerBy"="<Your name>" }
Below is an example of metadata you can set in the optional releaseProperties argument using build and release variables.
-releaseProperties @{ "BuildNumber"="$(Build.BuildNumber)"; "BuildRepositoryName"="$(Build.Repository.Name)"; "BuildRepositoryProvider"="$(Build.Repository.Provider)"; "ReleaseDefinitionName"="$(Build.DefinitionName)"; "ReleaseDescription"="Triggered by $(Build.DefinitionName) $(Build.BuildNumber)"; "ReleaseEnvironmentName"="$(Release.EnvironmentName)"; "ReleaseId"="$(Release.ReleaseId)"; "ReleaseName"="$(Release.ReleaseName)"; "ReleaseRequestedFor"="$(Release.RequestedFor)"; "ReleaseWebUrl"="$(Release.ReleaseWebUrl)"; "SourceBranch"="$(Build.SourceBranch)"; "TeamFoundationCollectionUri"="$(System.TeamFoundationCollectionUri)" }
Save.
Create release annotations with Azure CLI
You can use the CreateReleaseAnnotation PowerShell script to create annotations from any process you like, without using Azure DevOps.
Sign into Azure CLI.
Make a local copy of the script below and call it CreateReleaseAnnotation.ps1.
param( [parameter(Mandatory = $true)][string]$aiResourceId, [parameter(Mandatory = $true)][string]$releaseName, [parameter(Mandatory = $false)]$releaseProperties = @() ) $annotation = @{ Id = [GUID]::NewGuid(); AnnotationName = $releaseName; EventTime = (Get-Date).ToUniversalTime().GetDateTimeFormats("s")[0]; Category = "Deployment"; #Application Insights only displays annotations from the "Deployment" Category Properties = ConvertTo-Json $releaseProperties -Compress } $body = (ConvertTo-Json $annotation -Compress) -replace '(\\+)"', '$1$1"' -replace "`"", "`"`"" az rest --method put --uri "$($aiResourceId)/Annotations?api-version=2015-05-01" --body "$($body) " # Use the following command for Linux Azure DevOps Hosts or other PowerShell scenarios # Invoke-AzRestMethod -Path "$aiResourceId/Annotations?api-version=2015-05-01" -Method PUT -Payload $body
[!NOTE] Your annotations must have Category set to Deployment in order to be displayed in the Azure Portal.
Call the PowerShell script with the following code, replacing the angle-bracketed placeholders with your values. The -releaseProperties are optional.
.\CreateReleaseAnnotation.ps1 ` -aiResourceId "<aiResourceId>" ` -releaseName "<releaseName>" ` -releaseProperties @{"ReleaseDescription"="<a description>"; "TriggerBy"="<Your name>" }
Argument | Definition | Note |
---|---|---|
aiResourceId | The Resource ID to the target Application Insights resource. | Example: /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MyRGName/providers/microsoft.insights/components/MyResourceName |
releaseName | The name to give the created release annotation. | |
releaseProperties | Used to attach custom metadata to the annotation. | Optional |
View annotations
Note
Release annotations are not currently available in the Metrics pane of Application Insights
Now, whenever you use the release template to deploy a new release, an annotation is sent to Application Insights. The annotations can be viewed in the following locations:
Performance
Failures
Usage
Workbooks
In any log-based workbook query where the visualization displays time along the x-axis.
To enable annotations in your workbook, go to Advanced Settings and select Show annotations.
Select any annotation marker to open details about the release, including requestor, source control branch, release pipeline, and environment.
Release annotations using API keys
Release annotations are a feature of the cloud-based Azure Pipelines service of Azure DevOps.
Important
Annotations using API keys is deprecated. We recommend using Azure CLI instead.
Install the annotations extension (one time)
To be able to create release annotations, you'll need to install one of the many Azure DevOps extensions available in the Visual Studio Marketplace.
Sign in to your Azure DevOps project.
On the Visual Studio Marketplace Release Annotations extension page, select your Azure DevOps organization, and then select Install to add the extension to your Azure DevOps organization.
You only need to install the extension once for your Azure DevOps organization. You can now configure release annotations for any project in your organization.
Configure release annotations using API keys
Create a separate API key for each of your Azure Pipelines release templates.
Sign in to the Azure portal and open the Application Insights resource that monitors your application. Or if you don't have one, create a new Application Insights resource.
Open the API Access tab and copy the Application Insights ID.
In a separate browser window, open or create the release template that manages your Azure Pipelines deployments.
Select Add task, and then select the Application Insights Release Annotation task from the menu.
Note
The Release Annotation task currently supports only Windows-based agents; it won't run on Linux, macOS, or other types of agents.
Under Application ID, paste the Application Insights ID you copied from the API Access tab.
Back in the Application Insights API Access window, select Create API Key.
In the Create API key window, type a description, select Write annotations, and then select Generate key. Copy the new key.
In the release template window, on the Variables tab, select Add to create a variable definition for the new API key.
Under Name, enter
ApiKey
, and under Value, paste the API key you copied from the API Access tab.Select Save in the main release template window to save the template.
Note
Limits for API keys are described in the REST API rate limits documentation.
Transition to the new release annotation
To use the new release annotations:
- Remove the Release Annotations extension.
- Remove the Application Insights Release Annotation task in your Azure Pipelines deployment.
- Create new release annotations with Azure Pipelines or Azure CLI.
Next steps
Feedback
Submit and view feedback for