Skip to content

Commit 4c59fe2

Browse files
ShawnJacksonShawnJackson
authored
Merge pull request #228097 from paulth1/app-articles-batch-20
[AQ] edit pass: App articles batch 20
2 parents 7bfe6b8 + a1c5a35 commit 4c59fe2

File tree

5 files changed

+244
-253
lines changed

5 files changed

+244
-253
lines changed

‎articles/azure-monitor/app/annotations.md

Lines changed: 76 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -9,16 +9,16 @@ ms.reviewer: casocha
99

1010
# Release annotations for Application Insights
1111

12-
Annotations show where you deployed a new build, or other significant events. Annotations make it easy to see whether your changes had any effect on your application's performance. They can be automatically created by the [Azure Pipelines](/azure/devops/pipelines/tasks/) build system. You can also create annotations to flag any event you like by creating them from PowerShell.
12+
Annotations show where you deployed a new build or other significant events. Annotations make it easy to see whether your changes had any effect on your application's performance. They can be automatically created by the [Azure Pipelines](/azure/devops/pipelines/tasks/) build system. You can also create annotations to flag any event you want by creating them from PowerShell.
1313

1414
## Release annotations with Azure Pipelines build
1515

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

1818
If all the following criteria are met, the deployment task creates the release annotation automatically:
1919

20-
- The resource you're deploying to is linked to Application Insights (via the `APPINSIGHTS_INSTRUMENTATIONKEY` app setting).
21-
- The Application Insights resource is in the same subscription as the resource you're deploying to.
20+
- The resource to which you're deploying is linked to Application Insights via the `APPINSIGHTS_INSTRUMENTATIONKEY` app setting.
21+
- The Application Insights resource is in the same subscription as the resource to which you're deploying.
2222
- You're using one of the following Azure DevOps pipeline tasks:
2323

2424
| Task code | Task name | Versions |
@@ -31,19 +31,21 @@ If all the following criteria are met, the deployment task creates the release a
3131
| AzureWebApp | Azure Web App | Any |
3232

3333
> [!NOTE]
34-
> If you’re still using the Application Insights annotation deployment task, you should delete it.
34+
> If you're still using the Application Insights annotation deployment task, you should delete it.
3535
3636
### Configure release annotations
3737

38-
If you can't use one the deployment tasks in the previous section, then you need to add an inline script task in your deployment pipeline.
38+
If you can't use one of the deployment tasks in the previous section, you need to add an inline script task in your deployment pipeline.
3939

40-
1. Navigate to a new or existing pipeline and select a task.
41-
:::image type="content" source="./media/annotations/task.png" alt-text="Screenshot of task in stages selected." lightbox="./media/annotations/task.png":::
40+
1. Go to a new or existing pipeline and select a task.
41+
42+
:::image type="content" source="./media/annotations/task.png" alt-text="Screenshot that shows a task selected under Stages." lightbox="./media/annotations/task.png":::
4243
1. Add a new task and select **Azure CLI**.
43-
:::image type="content" source="./media/annotations/add-azure-cli.png" alt-text="Screenshot of adding a new task and selecting Azure CLI." lightbox="./media/annotations/add-azure-cli.png":::
44-
1. Specify the relevant Azure subscription. Change the **Script Type** to *PowerShell* and **Script Location** to *Inline*.
45-
1. Add the [PowerShell script from step 2 in the next section](#create-release-annotations-with-azure-cli) to **Inline Script**.
46-
1. Add the arguments below, replacing the angle-bracketed placeholders with your values to **Script Arguments**. The -releaseProperties are optional.
44+
45+
:::image type="content" source="./media/annotations/add-azure-cli.png" alt-text="Screenshot that shows adding a new task and selecting Azure CLI." lightbox="./media/annotations/add-azure-cli.png":::
46+
1. Specify the relevant Azure subscription. Change **Script Type** to **PowerShell** and **Script Location** to **Inline**.
47+
1. Add the [PowerShell script from step 2 in the next section](#create-release-annotations-with-the-azure-cli) to **Inline Script**.
48+
1. Add the following arguments. Replace the angle-bracketed placeholders with your values to **Script Arguments**. The `-releaseProperties` are optional.
4749

4850
```powershell
4951
-aiResourceId "<aiResourceId>" `
@@ -54,8 +56,7 @@ If you can't use one the deployment tasks in the previous section, then you need
5456
5557
:::image type="content" source="./media/annotations/inline-script.png" alt-text="Screenshot of Azure CLI task settings with Script Type, Script Location, Inline Script, and Script Arguments highlighted." lightbox="./media/annotations/inline-script.png":::
5658
57-
Below is an example of metadata you can set in the optional releaseProperties argument using [build](/azure/devops/pipelines/build/variables#build-variables-devops-services) and [release](/azure/devops/pipelines/release/variables#default-variables---release) variables.
58-
59+
The following example shows metadata you can set in the optional `releaseProperties` argument by using [build](/azure/devops/pipelines/build/variables#build-variables-devops-services) and [release](/azure/devops/pipelines/release/variables#default-variables---release) variables.
5960
6061
```powershell
6162
-releaseProperties @{
@@ -73,15 +74,15 @@ If you can't use one the deployment tasks in the previous section, then you need
7374
"TeamFoundationCollectionUri"="$(System.TeamFoundationCollectionUri)" }
7475
```
7576
76-
1. Save.
77+
1. Select **Save**.
7778
78-
## Create release annotations with Azure CLI
79+
## Create release annotations with the Azure CLI
7980
80-
You can use the CreateReleaseAnnotation PowerShell script to create annotations from any process you like, without using Azure DevOps.
81+
You can use the `CreateReleaseAnnotation` PowerShell script to create annotations from any process you want without using Azure DevOps.
8182
82-
1. Sign into [Azure CLI](/cli/azure/authenticate-azure-cli).
83+
1. Sign in to the [Azure CLI](/cli/azure/authenticate-azure-cli).
8384
84-
2. Make a local copy of the script below and call it CreateReleaseAnnotation.ps1.
85+
1. Make a local copy of the following script and call it `CreateReleaseAnnotation.ps1`.
8586
8687
```powershell
8788
param(
@@ -105,10 +106,10 @@ You can use the CreateReleaseAnnotation PowerShell script to create annotations
105106
# Invoke-AzRestMethod -Path "$aiResourceId/Annotations?api-version=2015-05-01" -Method PUT -Payload $body
106107
```
107108
108-
[!NOTE]
109-
Your annotations must have **Category** set to **Deployment** in order to be displayed in the Azure Portal.
109+
> [!NOTE]
110+
> Your annotations must have **Category** set to **Deployment** to appear in the Azure portal.
110111
111-
3. Call the PowerShell script with the following code, replacing the angle-bracketed placeholders with your values. The -releaseProperties are optional.
112+
1. Call the PowerShell script with the following code. Replace the angle-bracketed placeholders with your values. The `-releaseProperties` are optional.
112113
113114
```powershell
114115
.\CreateReleaseAnnotation.ps1 `
@@ -118,111 +119,109 @@ You can use the CreateReleaseAnnotation PowerShell script to create annotations
118119
"TriggerBy"="<Your name>" }
119120
```
120121
121-
|Argument | Definition | Note|
122-
|--------------|-----------------------|--------------------|
123-
|aiResourceId | The Resource ID to the target Application Insights resource. | Example:<br> /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MyRGName/providers/microsoft.insights/components/MyResourceName|
124-
|releaseName | The name to give the created release annotation. | |
125-
|releaseProperties | Used to attach custom metadata to the annotation. | Optional|
126-
127-
122+
|Argument | Definition | Note|
123+
|--------------|-----------------------|--------------------|
124+
|`aiResourceId` | The resource ID to the target Application Insights resource. | Example:<br> /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MyRGName/providers/microsoft.insights/components/MyResourceName|
125+
|`releaseName` | The name to give the created release annotation. | |
126+
|`releaseProperties` | Used to attach custom metadata to the annotation. | Optional|
127+
128128
## View annotations
129129
130130
> [!NOTE]
131-
> Release annotations are not currently available in the Metrics pane of Application Insights
131+
> Release annotations aren't currently available in the **Metrics** pane of Application Insights.
132132
133-
Now, whenever you use the release template to deploy a new release, an annotation is sent to Application Insights. The annotations can be viewed in the following locations:
133+
Whenever you use the release template to deploy a new release, an annotation is sent to Application Insights. You can view annotations in the following locations:
134134
135-
- Performance
135+
- **Performance:**
136136
137-
:::image type="content" source="./media/annotations/performance.png" alt-text="Screenshot of the Performance tab with a release annotation selected(blue arrow) to show the Release Properties tab." lightbox="./media/annotations/performance.png":::
137+
:::image type="content" source="./media/annotations/performance.png" alt-text="Screenshot that shows the Performance tab with a release annotation selected to show the Release Properties tab." lightbox="./media/annotations/performance.png":::
138138
139-
- Failures
139+
- **Failures:**
140140
141-
:::image type="content" source="./media/annotations/failures.png" alt-text="Screenshot of the Failures tab with a release annotation (blue arrow) selected to show the Release Properties tab." lightbox="./media/annotations/failures.png":::
142-
- Usage
141+
:::image type="content" source="./media/annotations/failures.png" alt-text="Screenshot that shows the Failures tab with a release annotation selected to show the Release Properties tab." lightbox="./media/annotations/failures.png":::
142+
- **Usage:**
143143
144-
:::image type="content" source="./media/annotations/usage-pane.png" alt-text="Screenshot of the Users tab bar with release annotations selected. Release annotations appear as blue arrows above the chart indicating the moment in time that a release occurred." lightbox="./media/annotations/usage-pane.png":::
144+
:::image type="content" source="./media/annotations/usage-pane.png" alt-text="Screenshot that shows the Users tab bar with release annotations selected. Release annotations appear as blue arrows above the chart indicating the moment in time that a release occurred." lightbox="./media/annotations/usage-pane.png":::
145145
146-
- Workbooks
146+
- **Workbooks:**
147147
148-
In any log-based workbook query where the visualization displays time along the x-axis.
148+
In any log-based workbook query where the visualization displays time along the x-axis:
149149
150-
:::image type="content" source="./media/annotations/workbooks-annotations.png" alt-text="Screenshot of workbooks pane with time series log-based query with annotations displayed." lightbox="./media/annotations/workbooks-annotations.png":::
150+
:::image type="content" source="./media/annotations/workbooks-annotations.png" alt-text="Screenshot that shows the Workbooks pane with a time series log-based query with annotations displayed." lightbox="./media/annotations/workbooks-annotations.png":::
151151
152-
To enable annotations in your workbook, go to **Advanced Settings** and select **Show annotations**.
152+
To enable annotations in your workbook, go to **Advanced Settings** and select **Show annotations**.
153153
154-
:::image type="content" source="./media/annotations/workbook-show-annotations.png" alt-text="Screenshot of Advanced Settings menu with the show annotations checkbox highlighted.":::
154+
:::image type="content" source="./media/annotations/workbook-show-annotations.png" alt-text="Screenshot that shows the Advanced Settings menu with the show annotations checkbox highlighted.":::
155155
156156
Select any annotation marker to open details about the release, including requestor, source control branch, release pipeline, and environment.
157157
158-
## Release annotations using API keys
158+
## Release annotations by using API keys
159159
160160
Release annotations are a feature of the cloud-based Azure Pipelines service of Azure DevOps.
161161
162162
> [!IMPORTANT]
163-
> Annotations using API keys is deprecated. We recommend using [Azure CLI](#create-release-annotations-with-azure-cli) instead.
163+
> Annotations using API keys is deprecated. We recommend using the [Azure CLI](#create-release-annotations-with-the-azure-cli) instead.
164164
165165
### Install the annotations extension (one time)
166166
167-
To be able to create release annotations, you'll need to install one of the many Azure DevOps extensions available in the Visual Studio Marketplace.
167+
To create release annotations, install one of the many Azure DevOps extensions available in Visual Studio Marketplace.
168168
169169
1. Sign in to your [Azure DevOps](https://azure.microsoft.com/services/devops/) project.
170-
171-
1. On the Visual Studio Marketplace [Release Annotations extension](https://marketplace.visualstudio.com/items/ms-appinsights.appinsightsreleaseannotations) page, select your Azure DevOps organization, and then select **Install** to add the extension to your Azure DevOps organization.
172-
173-
![Select an Azure DevOps organization and then select Install.](./media/annotations/1-install.png)
174-
170+
171+
1. On the **Visual Studio Marketplace** [Release Annotations extension](https://marketplace.visualstudio.com/items/ms-appinsights.appinsightsreleaseannotations) page, select your Azure DevOps organization. Select **Install** to add the extension to your Azure DevOps organization.
172+
173+
![Screenshot that shows selecting an Azure DevOps organization and selecting Install.](./media/annotations/1-install.png)
174+
175175
You only need to install the extension once for your Azure DevOps organization. You can now configure release annotations for any project in your organization.
176176
177-
### Configure release annotations using API keys
177+
### Configure release annotations by using API keys
178178
179179
Create a separate API key for each of your Azure Pipelines release templates.
180180
181181
1. Sign in to the [Azure portal](https://portal.azure.com) and open the Application Insights resource that monitors your application. Or if you don't have one, [create a new Application Insights resource](create-workspace-resource.md).
182-
182+
183183
1. Open the **API Access** tab and copy the **Application Insights ID**.
184-
185-
![Under API Access, copy the Application ID.](./media/annotations/2-app-id.png)
184+
185+
![Screenshot that shows under API Access, copying the Application ID.](./media/annotations/2-app-id.png)
186186
187187
1. In a separate browser window, open or create the release template that manages your Azure Pipelines deployments.
188+
189+
1. Select **Add task** and then select the **Application Insights Release Annotation** task from the menu.
188190
189-
1. Select **Add task**, and then select the **Application Insights Release Annotation** task from the menu.
190-
191-
![Select Add Task and select Application Insights Release Annotation.](./media/annotations/3-add-task.png)
191+
![Screenshot that shows selecting Add Task and Application Insights Release Annotation.](./media/annotations/3-add-task.png)
192192
193193
> [!NOTE]
194-
> The Release Annotation task currently supports only Windows-based agents; it won't run on Linux, macOS, or other types of agents.
195-
194+
> The Release Annotation task currently supports only Windows-based agents. It won't run on Linux, macOS, or other types of agents.
195+
196196
1. Under **Application ID**, paste the Application Insights ID you copied from the **API Access** tab.
197-
198-
![Paste the Application Insights ID](./media/annotations/4-paste-app-id.png)
199-
200-
1. Back in the Application Insights **API Access** window, select **Create API Key**.
201-
202-
![In the API Access tab, select Create API Key.](./media/annotations/5-create-api-key.png)
203-
204-
1. In the **Create API key** window, type a description, select **Write annotations**, and then select **Generate key**. Copy the new key.
205-
206-
![In the Create API key window, type a description, select Write annotations, and then select Generate key.](./media/annotations/6-create-api-key.png)
207-
197+
198+
![Screenshot that shows pasting the Application Insights ID.](./media/annotations/4-paste-app-id.png)
199+
200+
1. Back in the Application Insights **API Access** window, select **Create API Key**.
201+
202+
![Screenshot that shows selecting the Create API Key on the API Access tab.](./media/annotations/5-create-api-key.png)
203+
204+
1. In the **Create API key** window, enter a description, select **Write annotations**, and then select **Generate key**. Copy the new key.
205+
206+
![Screenshot that shows in the Create API key window, entering a description, selecting Write annotations, and then selecting the Generate key.](./media/annotations/6-create-api-key.png)
207+
208208
1. In the release template window, on the **Variables** tab, select **Add** to create a variable definition for the new API key.
209209
210-
1. Under **Name**, enter `ApiKey`, and under **Value**, paste the API key you copied from the **API Access** tab.
211-
212-
![In the Azure DevOps Variables tab, select Add, name the variable ApiKey, and paste the API key under Value.](./media/annotations/7-paste-api-key.png)
213-
214-
1. Select **Save** in the main release template window to save the template.
210+
1. Under **Name**, enter **ApiKey**. Under **Value**, paste the API key you copied from the **API Access** tab.
215211
212+
![Screenshot that shows in the Azure DevOps Variables tab, selecting Add, naming the variable ApiKey, and pasting the API key under Value.](./media/annotations/7-paste-api-key.png)
213+
214+
1. Select **Save** in the main release template window to save the template.
216215
217216
> [!NOTE]
218217
> Limits for API keys are described in the [REST API rate limits documentation](/rest/api/yammer/rest-api-rate-limits).
219218
220219
### Transition to the new release annotation
221220
222-
To use the new release annotations:
221+
To use the new release annotations:
223222
1. [Remove the Release Annotations extension](/azure/devops/marketplace/uninstall-disable-extensions).
224-
1. Remove the Application Insights Release Annotation task in your Azure Pipelines deployment.
225-
1. Create new release annotations with [Azure Pipelines](#release-annotations-with-azure-pipelines-build) or [Azure CLI](#create-release-annotations-with-azure-cli).
223+
1. Remove the Application Insights Release Annotation task in your Azure Pipelines deployment.
224+
1. Create new release annotations with [Azure Pipelines](#release-annotations-with-azure-pipelines-build) or the [Azure CLI](#create-release-annotations-with-the-azure-cli).
226225
227226
## Next steps
228227

0 commit comments

Comments
 (0)