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 Azure DevOps 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 Azure DevOps Services build

Release annotations are a feature of the cloud-based Azure Pipelines service of Azure DevOps Services.

Install the Annotations extension (one time)

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

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

At top right of the Azure DevOps Services web page, open Marketplace. Select Azure DevOps Services and then under Azure Pipelines, choose See More.

You only need to do this once for your Azure DevOps Services organization. Release annotations can now be configured for any project in your organization.

Configure release annotations

You need to get a separate API key for each Azure DevOps Services 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 Azure DevOps 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 Azure DevOps Services, open Release, select a release pipeline, 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 Azure DevOps 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 pipeline.

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 pipeline, 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 Azure DevOps Services).

  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