Release Annotations

This functionality had been available previously under the name “Deployment Markers” back when Application Insights existed under Visual Studio Online.  Release Annotations for Application Insights is an extension for Visual Studio Team Services (VSTS) and Team Foundation Server (TFS) 2015 Update 2 that will create annotations on the Application Insights Metrics Explorer timeline.

Release Annotations in Metrics Explorer

To get started you will need to install or download the extension from the Visual Studio Marketplace depending on whether you are using VSTS or TFS.

To install Release Annotations for Application Insights on TFS 2015 Update 2 (on-premises), perform the following steps:

• Navigate to the TFS Extensions page on your server.
  (Example: http://tfs.local:8080/tfs/_gallery/manage)
• Click Upload new extension and select the file you have just downloaded.  Wait for the extension to be successfully uploaded
• click Install and select the Team Project Collection (TPC) to install into.

For this blog post I am going to be using VSTS and leverage a release definition I created for an earlier blog post on the new Release Management.  Here is how the release definition Publish Website looks currently:

Release Definition: Publish Website

Now obviously Release Annotations requires Application Insights be added to your web application, it doesn’t matter whether your web application is hosted in IIS on-premises, IIS in a VM in Azure, or an App Service in Microsoft Azure.

No Application Insights option? Check that you’re using VS 2013 Update 3 or later and that Application Insights Tools are enabled in Extensions and Updates.

If I am creating a New Web Application in Visual Studio 2015 I can add Application Insights using the New Project Wizard:

• (1) Add Application Insights to project
• (2) Your Microsoft Account or Organization ID for Azure
• (3) Select the Azure Subscription
• (4) Send telemetry to:
  • New Application Insights resource
  • Install SDK Only
  • Existing Application Insights resource

More documentation on configuring Application Insights in VS can be found here.

VS 2015 New Project Wizard

In this example I will modify a Release Definition to include the Release Annotation task, make sure you have the task “installed” for Team Services or “downloaded and installed” for Team Foundation Server (requires Update 2).  See instructions above.

Select your Release Definition displayed under Releases and Click Edit to the right of the name of your definition:

• Select the environment Default Environment if not already selected
• (1) Click + Add tasks
• (2) Click the Deploy category
• (3) scroll down until you can see Release Annotation, click Add
• (4) Click Close

Add Release Annotation

Now the task will automaticall be added to the end of your tasks and depending on your point of view this may be perfectly alright as all of the previous tasks must succeed before the Release Annotation task is executed.

Let’s configure two (2) variables for the following values required by this task:

• (1) Application ID: $(ApplicationID)
• (2) API Key: $(ApiKey)
• (3) Click Configuration 
  Note: You could also define these variables per environment by clicking the elipsis to the right of the environment name and selecting Configure variables

Add release annotation to Application Insights resource

On the Configuration page add two variables:

• Click + Add variable
• Type ApplicationID for the name
• Click + Add variable
• Type ApiKey for the name

Configuration (Global Variables)

You can populate the values for these variable by going to the Azure Portal, open the Application Insights resource that is monitoring your application.  Open API Access and select Create API Key.

Application Insights | API Access | Create API Key

Release annotations on Metrics Explorer charts in Application Insights show when you deployed a new build.

Happy monitoring, you can read more abou this feature at this Azure blog post.