They’re baaaaaccccckkkkk!

I could not be happier to announce that Release Annotations (formerly known as “deployment markers”) are now live in Application Insights. This has been one of the most-requested bits of functionality since Application Insights moved from Visual Studio Online (now Visual Studio Team Services) to the new Azure portal.

Release Annotations can be displayed on the Metrics Explorer, and allow you to correlate the time your release took place to the many metrics available on the blade. This helps you understand things like whether a bad (or good) deployment is negatively affecting your service or app.

Enabling Release Annotations

To show Release Annotations on your Metrics Explorer, you’ll need to add them to your build in VSTS.  In order to make them available, you can simply add the extension from the Visual Studio Marketplace.

Once you drill into the page for the Release Annotations extension, click the Install button.

You’ll then be presented with an authorization window to associate the extension to a VSTS subscription.

After you confirm, you’ll be ready to start adding Release Annotations to any of your VSTS releases.

Adding Release Annotations to a VSTS Release

Now that Release Annotations are enabled, you can add them to any releases associated with the selected subscription in VSTS.  Simply edit an existing release, click on Add tasks, and select Release Annotation from the list of available tasks (listed in the Deploy section).

After the step is added, you’ll need to generate and add an API key from Application Insights to finish filling out the attributes for the step. For full, detailed instructions on this process, please see our documentation page. Once this is done, the next time your release runs, a Release Annotation will be generated.

One question I’ve already gotten quite a bit is, “Does it matter where in the step order I put this task?” The answer is no. In fact, you could add this task more than once if you’d like. Now, under normal circumstances, there wouldn’t be much point to doing that. But, if you have a very complex release that takes quite a bit of time to run, it’s plausible that you may want to mark each “phase” of the release, and in that case, you may end up with multiple Release Annotation tasks. We are already discussing future design possibilities around how to associate related Annotations and represent events that may have long durations.  This will become more significant as the capabilities of VSTS release functionality grows.

Viewing Annotations

You’re now ready to view your Release Annotations. They will be available on all Metrics Explorer blades. When you open a Metrics Explorer blade, you’ll now see your Release Annotations as informational icons at the top of the available charts. When you hover over any of them, you’ll get an info balloon that will give you some of the specifics about your release. You can use this info and the relative position of the Annotation to correlate the release with other available metrics to determine if the release potentially affected your resource.

Another important thing to note is that we are currently working on a detail blade for Release Annotations that will provide a broader variety of data regarding the release. This functionality will become available over the next couple of sprints.

The future of Annotations

It is very important to understand that the current Annotations functionality is in its infancy. You’ll note the proper case whenever the word “Annotation” is mentioned. This is because Release Annotations are simply the first of many kinds of Annotations we want to make available to you in Application Insights. We’re currently already testing a variety of operational events as Annotations internally, and have drafted the high-level conceptual design for many others.

We’d also like to give users the capability to create manual Annotations, or even define custom kinds of Annotations they can reuse across a resource or subscription. There are plans for making Annotations available in more places in Application Insights, allowing for direct injection of Annotations from third-party products (via an API), showing multiple kinds of Annotations in swim lanes, ways to represent events that have duration (or multiple phases), grouping for multiple Annotations created at the same time, and a subscription model to select which Kinds of Annotations the user would like to generate/view. That’s not even mentioning things we’d like to do in terms of associating Annotations with Work Items or viewing the data directly in Visual Studio.

Our team has big plans here, but we’ll also be looking to your feedback to help us prioritize and evolve features. Most importantly, keep checking back here on the Azure blog for more announcements as things progress. We are just getting started.

Please share your ideas for new or improved features at the Application Insights User Voice page and for any questions visit the Application Insights Forum.