When it comes to developing and delivering products and solutions it’s important to be in control of updates and releases, and be able to do rollouts with confidence. Logging and monitoring is essential to understand the behavior of our application, and to ensure stability.

So, how can you control and monitor the impact that your releases have on your solutions? If you are working in the Azure ecosystem, chances are high that you have used, or at least heard about Application Insights. Application Insights is a powerful service that gather and visualizes logs from your applications, offering insights into the apps performance, health, and usage patterns. It also provides additional features that can improve your monitoring and understanding of events, this feature is called release annotations.

Release annotations are small markers or highlights on your charts which shows you when a new release has occurred, and in that way gives you valuable insights and context, which makes it easier to correlate issues with specific releases or changes to your application.

Below you can see how the different releases are displayed in Application Insights. The examples show the annotations on the failure charts which makes it easy to spot if there was an increased failure rate after the deployment happened.

The annotations will also be displayed when running custom KQL queries in your workbooks.

If you are using Azure DevOps, some built-in release tasks automatically generate release annotations for you (check the table below to see which is supported).

This is a nice feature for your deployments from Azure DevOps Pipelines, but have you ever considered that your changes to configuration, feature flags or infrastructure could be considered a release as well?

For instance, modifying configuration in external configuration services like Azure App Configuration won’t trigger an automatic annotation and will have to be handled differently. The same goes for your IaC deploys that may contain configuration changes, or even infrastructure changes. These changes, despite not involving a traditional deployment can introduce issues or impact your application’s performance.

By treating these changes as you would with code releases, and manually adding annotations to your telemetry, you will ensure better monitoring by increasing the understanding for what is affecting your solutions.

The following script will make a manual release annotation, wherever you may need it in your processes, by following some simple steps.

1. Create annotation: Generates an annotation object with a unique ID, release name, timestamp, category (“Deployment”), and additional properties serialized to JSON.
2. Prepare JSON: Converts the annotation to a compressed JSON string and encodes unicode characters for compatibility.
3. Get access token: Fetches an Azure access token using the Azure CLI.
4. Set headers: Configures HTTP headers for authorization and content type.
5. Send request: Sends a PUT request to the Azure Management API to save the annotation.

$annotation = @{
    Id = [GUID]::NewGuid();
    AnnotationName = $releaseName;
    EventTime = (Get-Date).ToUniversalTime().GetDateTimeFormats("s")[0];
    Category = "Deployment";
    Properties = ConvertTo-Json $releaseProperties -Compress
}

$annotation = ConvertTo-Json $annotation -Compress
$annotation = Convert-UnicodeToEscapeHex -JsonString $annotation  

$accessToken = (az account get-access-token | ConvertFrom-Json).accessToken
$headers = @{
    "Authorization" = "Bearer $accessToken"
    "Accept"        = "application/json"
    "Content-Type"  = "application/json"
}
$params = @{
    Headers = $headers
    Method  = "Put"
    Uri     = "https://management.azure.com$($aiResourceId)/Annotations?api-version=2015-05-01"
    Body    = $annotation
}
Invoke-RestMethod @params

For a complete code sample you can refer to the documentation over at Release and work item insights for Application Insights – Azure Monitor | Microsoft Learn

After saving the script to a PowerShell file you can try to run the script to create an annotation like this:

.\releaseannotation.ps1 -aiResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/microsoft.insights/components/<resourceName>" -releaseName "fh-blog" -releaseProperties @{"ReleaseDescription"="New feature!";"TriggerBy"="Frank" }

After the script has executed successfully you should see the annotation in Application Insights.

Treating all changes, deployments, configurations, and feature flags as releases provides a complete picture of their impact on your application. With proper annotations, you can spot the root cause of issues faster and maintain a reliable system.