Annotations on metric charts in Application Insights

Annotations on Metrics Explorer charts show where you deployed a new build, or other significant event. They make it easy to see whether your changes had any effect on your application's performance. They can be automatically created by the Visual Studio Team Services build system. You can also create annotations to flag any event you like by creating them from PowerShell.

Example of annotations with visible correlation with server response time

Release annotations with VSTS build

Release annotations are a feature of the cloud-based build and release service of Visual Studio Team Services.

Install the Annotations extension (one time)

To be able to create release annotations, you'll need to install one of the many Team Service extensions available in the Visual Studio Marketplace.

  1. Sign in to your Visual Studio Team Services project.
  2. In Visual Studio Marketplace, get the Release Annotations extension, and add it to your Team Services account.

At top right of Team Services web page, open Marketplace. Select Visual Team Services and then under Build and Release, choose See More.

You only need to do this once for your Visual Studio Team Services account. Release annotations can now be configured for any project in your account.

Configure release annotations

You need to get a separate API key for each VSTS release template.

  1. Sign in to the Microsoft Azure Portal and open the Application Insights resource that monitors your application. (Or create one now, if you haven't done so yet.)
  2. Open API Access, Application Insights Id.

    In portal.azure.com, open your Application Insights resource and choose Settings. Open API Access. Copy the Application ID

  3. In a separate browser window, open (or create) the release template that manages your deployments from Visual Studio Team Services.

    Add a task, and select the Application Insights Release Annotation task from the menu.

    Paste the Application Id that you copied from the API Access blade.

    In Visual Studio Team Services, open Release, select a release definition, and choose Edit. Click Add Task and select Application Insights Release Annotation. Paste the Application Insights Id.

  4. Set the APIKey field to a variable $(ApiKey).

  5. Back in the Azure window, create a new API Key and take a copy of it.

    In the API Access blade in the Azure window, click Create API Key. Provide a comment, check Write annotations, and click Generate Key. Copy the new key.

  6. Open the Configuration tab of the release template.

    Create a variable definition for ApiKey.

    Paste your API key to the ApiKey variable definition.

    In the Team Services window, select the Configuration tab and click Add Variable. Set the name to ApiKey and into the Value, paste the key you just generated, and click the lock icon.

  7. Finally, Save the release definition.

View annotations

Now, whenever you use the release template to deploy a new release, an annotation will be sent to Application Insights. The annotations will appear on charts in Metrics Explorer.

Click on any annotation marker to open details about the release, including requestor, source control branch, release definition, environment, and more.

Click any release annotation marker.

Create custom annotations from PowerShell

You can also create annotations from any process you like (without using VS Team System).

  1. Make a local copy of the Powershell script from GitHub.

  2. Get the Application ID and create an API key from the API Access blade.

  3. Call the script like this:


     .\CreateReleaseAnnotation.ps1 `
      -applicationId "<applicationId>" `
      -apiKey "<apiKey>" `
      -releaseName "<myReleaseName>" `
      -releaseProperties @{
          "ReleaseDescription"="a description";
          "TriggerBy"="My Name" }

It's easy to modify the script, for example to create annotations for the past.

Next steps