Skip to content

Commit a398ac0

Browse files
TrishaMcTrishaMc
authored
Merge pull request #42884 from msvijayn/vijayn-docs
Doc update for Alert Extend
2 parents d41c851 + f379a37 commit a398ac0

File tree

2 files changed

+254
-24
lines changed

2 files changed

+254
-24
lines changed

‎articles/monitoring-and-diagnostics/monitoring-alerts-extend-tool.md

Lines changed: 250 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,15 @@ ms.workload: na
1212
ms.tgt_pltfrm: na
1313
ms.devlang: na
1414
ms.topic: article
15-
ms.date: 05/30/2018
15+
ms.date: 06/04/2018
1616
ms.author: vinagara
1717

1818
---
1919
# How to migrate alerts from Log Analytics into Azure Alerts
2020
Alerts in Log Analytics is being replaced by Azure Alerts and as part of this transition, alerts that you configured in Log Analytics will be migrated into Azure. If you don't want to wait for them to be automatically moved into Azure, you can initiate the process following one of the options:
2121

2222
1. Manually from the OMS portal
23-
2. Programatically using the AlertsVersion API
23+
2. Programmatically using the AlertsVersion API
2424

2525
> [!NOTE]
2626
> Microsoft will automatically migrate alerts created in Log Analytics to Azure alerts starting on **14 May 2018** in a phased approach until completed. From this day forward, Microsoft will begin to schedule migrating the alerts to Azure, and during this transition, alerts can be managed from both the OMS portal and Azure portal. This process is nondestructive and not interruptive.
@@ -136,7 +136,7 @@ armclient POST /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupNam
136136
> [!NOTE]
137137
> Result of migrating alerts into Azure Alerts may vary based on the summary provided by GET response. Once scheduled, alerts in Log Analytics will be temporarily unavailable for editing/modification in the OMS portal. However, new alerts can be created.
138138
139-
If the POST resquest is successful, it returns a HTTP 200 OK status along with the following response:
139+
If the POST request is successful, it returns an HTTP 200 OK status along with the following response:
140140

141141
```json
142142
{
@@ -207,40 +207,270 @@ This response indicates the alerts have been successfully migrated into Azure Al
207207

208208
```
209209

210-
## Troubleshooting
211-
During the process of migrating your alerts from Log Analytics to Azure Alerts, an issue could prevent the service from creating the required [Action Groups](monitoring-action-groups.md). In such cases an error message will be shown in a banner at the top of the OMS portal under **Alert Settings** section and in the resulting JSON when you create a GET request.
212210

213-
Listed below are the remediation steps for each error:
211+
## Option 3 - Using custom PowerShell script
212+
After May 14, 2018 - if Microsoft has not successfully extended your alerts from OMS portal to Azure; then until **July 5, 2018** - user can manually do the same via [Option1 - Via GUI](#option-1---initiate-from-the-oms-portal) or [Option 2 - Via API](#option-2---using-the-alertsversion-api).
213+
214+
After **July 5, 2018** - all alerts from OMS portal will be extended into Azure. Users who didn't take the [necessary remediation steps suggested](#troubleshooting), will have their alerts running without firing actions or notifications due to the lack of associated [Action Groups](monitoring-action-groups.md).
215+
216+
To manually create [Action Groups](monitoring-action-groups.md) for alerts in Log Analytics, users can use the sample script below.
217+
```PowerShell
218+
########## Input Parameters Begin ###########
219+
220+
221+
$subscriptionId = ""
222+
$resourceGroup = ""
223+
$workspaceName = ""
224+
225+
226+
########## Input Parameters End ###########
227+
228+
armclient login
229+
230+
try
231+
{
232+
$workspace = armclient get /subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.OperationalInsights/workspaces/"$workspaceName"?api-version=2015-03-20 | ConvertFrom-Json
233+
$workspaceId = $workspace.properties.customerId
234+
$resourceLocation = $workspace.location
235+
}
236+
catch
237+
{
238+
"Please enter valid input parameters i.e. Subscription Id, Resource Group and Workspace Name !!"
239+
exit
240+
}
241+
242+
# Get Extend Summary of the Alerts
243+
"`nGetting Extend Summary of Alerts for the workspace...`n"
244+
try
245+
{
246+
247+
$value = armclient get /subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.OperationalInsights/workspaces/$workspaceName/alertsversion?api-version=2017-04-26-preview
248+
249+
"Extend preview summary"
250+
"=========================`n"
251+
252+
$value
253+
254+
$result = $value | ConvertFrom-Json
255+
}
256+
catch
257+
{
258+
259+
$ErrorMessage = $_.Exception.Message
260+
"Error occured while fetching/parsing Extend summary: $ErrorMessage"
261+
exit
262+
}
263+
264+
if ($result.version -eq 2)
265+
{
266+
"`nThe alerts in this workspace have already been extended to Azure."
267+
exit
268+
}
269+
270+
$in = Read-Host -Prompt "`nDo you want to continue extending the alerts to Azure? (Y/N)"
271+
272+
if ($in.ToLower() -ne "y")
273+
{
274+
exit
275+
}
276+
277+
278+
# Check for resource provider registration
279+
try
280+
{
281+
$val = armclient get subscriptions/$subscriptionId/providers/microsoft.insights/?api-version=2017-05-10 | ConvertFrom-Json
282+
if ($val.registrationState -eq "NotRegistered")
283+
{
284+
$val = armclient post subscriptions/$subscriptionId/providers/microsoft.insights/register/?api-version=2017-05-10
285+
}
286+
}
287+
catch
288+
{
289+
"`nThe user does not have required access to register the resource provider. Please try with user having Contributor/Owner role in the subscription"
290+
exit
291+
}
292+
293+
$actionGroupsMap = @{}
294+
try
295+
{
296+
"`nCreating new action groups for alerts extension...`n"
297+
foreach ($actionGroup in $result.migrationSummary.actionGroups)
298+
{
299+
$actionGroupName = $actionGroup.actionGroupName
300+
$actions = $actionGroup.actions
301+
if ($actionGroupsMap.ContainsKey($actionGroupName))
302+
{
303+
continue
304+
}
305+
306+
# Create action group payload
307+
$shortName = $actionGroupName.Substring($actionGroupName.LastIndexOf("AG_"))
308+
$properties = @{"groupShortName"= $shortName; "enabled" = $true}
309+
$emailReceivers = New-Object Object[] $actions.emailIds.Count
310+
$webhookReceivers = New-Object Object[] $actions.webhookActions.Count
311+
312+
$count = 0
313+
foreach ($email in $actions.emailIds)
314+
{
315+
$emailReceivers[$count] = @{"name" = "Email$($count+1)"; "emailAddress" = "$email"}
316+
$count++
317+
}
318+
319+
$count = 0
320+
foreach ($webhook in $actions.webhookActions)
321+
{
322+
$webhookReceivers[$count] = @{"name" = "$($webhook.name)"; "serviceUri" = "$($webhook.serviceUri)"}
323+
$count++
324+
}
325+
326+
$itsmAction = $actions.itsmAction
327+
if ($itsmAction.connectionId -ne $null)
328+
{
329+
$val = @{
330+
"name" = "ITSM"
331+
"workspaceId" = "$subscriptionId|$workspaceId"
332+
"connectionId" = "$($itsmAction.connectionId)"
333+
"ticketConfiguration" = $itsmAction.templateInfo
334+
"region" = "$resourceLocation"
335+
}
336+
$properties["itsmReceivers"] = @($val)
337+
}
214338
215-
1. **Error: The subscription is not registered to use the namespace 'microsoft.insights'**:
339+
$properties["emailReceivers"] = @($emailReceivers)
340+
$properties["webhookReceivers"] = @($webhookReceivers)
341+
$armPayload = @{"properties" = $properties; "location" = "Global"} | ConvertTo-Json -Compress -Depth 4
342+
343+
344+
# ARM call to create action group
345+
$response = $armPayload | armclient put /subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.insights/actionGroups/$actionGroupName/?api-version=2017-04-01
216346
217-
![OMS portal Alert Settings page with Registration Error message](./media/monitor-alerts-extend/ErrorMissingRegistration.png)
347+
"Created Action Group with name $actionGroupName"
348+
$actionGroupsMap[$actionGroupName] = $actionGroup.actionGroupResourceId.ToLower()
349+
$index++
350+
}
351+
352+
"`nSuccessfully created all action groups!!"
353+
}
354+
catch
355+
{
356+
$ErrorMessage = $_.Exception.Message
218357
219-
a. The subscription associated with your OMS workspace - has not been registered to use Azure Monitor (microsoft.insights) functionality; due to which OMS unable to extend you alerts into Azure Monitor & Alerts.
358+
#Delete all action groups in case of failure
359+
"`nDeleting newly created action groups if any as some error happened..."
220360
221-
b. To resolve, register microsoft.insights (Azure monitor & alerts) use in your subscription using Powershell, Azure CLI, or Azure portal. To learn more, view the article on [resolving errors on resource provider registration](../azure-resource-manager/resource-manager-register-provider-errors.md)
361+
foreach ($actionGroup in $actionGroupsMap.Keys)
362+
{
363+
$response = armclient delete /subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.insights/actionGroups/$actionGroup/?api-version=2017-04-01
364+
}
365+
366+
"`nError: $ErrorMessage"
367+
"`nExiting..."
368+
exit
369+
}
370+
371+
# Update all alerts configuration to the new version
372+
"`nExtending OMS alerts to Azure...`n"
373+
374+
try
375+
{
376+
$index = 1
377+
foreach ($alert in $result.migrationSummary.alerts)
378+
{
379+
$uri = $alert.alertId + "?api-version=2015-03-20"
380+
$config = armclient get $uri | ConvertFrom-Json
381+
$aznsNotification = @{
382+
"GroupIds" = @($actionGroupsMap[$alert.actionGroupName])
383+
}
384+
if ($alert.customWebhookPayload)
385+
{
386+
$aznsNotification.Add("CustomWebhookPayload", $alert.customWebhookPayload)
387+
}
388+
if ($alert.customEmailSubject)
389+
{
390+
$aznsNotification.Add("CustomEmailSubject", $alert.customEmailSubject)
391+
}
392+
393+
# Update alert version
394+
$config.properties.Version = 2
395+
396+
$config.properties | Add-Member -MemberType NoteProperty -Name "AzNsNotification" -Value $aznsNotification
397+
$payload = $config | ConvertTo-Json -Depth 4
398+
$response = $payload | armclient put $uri
222399
223-
c. Once resolved as per steps illustrated in the article, OMS will extend your alerts into Azure within the next day's scheduled run; without the need of any action or initiation.
400+
"Extended alert with name $($alert.alertName)"
401+
$index++
402+
}
403+
}
404+
catch
405+
{
406+
$ErrorMessage = $_.Exception.Message
407+
if ($index -eq 1)
408+
{
409+
"`nDeleting all newly created action groups as no alerts got extended..."
410+
foreach ($actionGroup in $actionGroupsMap.Keys)
411+
{
412+
$response = armclient delete /subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.insights/actionGroups/$actionGroup/?api-version=2017-04-01
413+
}
414+
"`nDeleted all action groups."
415+
}
416+
417+
"`nError: $ErrorMessage"
418+
"`nPlease resolve the issue and try extending again!!"
419+
"`nExiting..."
420+
exit
421+
}
422+
423+
"`nSuccessfully extended all OMS alerts to Azure!!"
424+
425+
# Update version of workspace to indicate extension
426+
"`nUpdating alert version information in OMS workspace..."
427+
428+
$response = armclient post "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.OperationalInsights/workspaces/$workspaceName/alertsversion?api-version=2017-04-26-preview&iversion=2"
429+
430+
"`nExtension complete!!"
431+
```
224432

225-
2. **Error: Scope Lock is present at subscription/resource group level for write operations**:
226433

434+
**Using the custom PowerShell script**
435+
- Pre-requisite is the installation of [ARMclient](https://github.com/projectkudu/ARMClient), an open-source command-line tool that simplifies invoking the Azure Resource Manager API
436+
- User running the said script must have Contributor or Owner role in the Azure Subscription
437+
- The following are the parameters to be provided for the script:
438+
- $subscriptionId: The Azure Subscription ID associated with the OMS/LA Workspace
439+
- $resourceGroup: The Azure Resource Group where lies the OMS/LA Workspace
440+
- $workspaceName: The name of the OMS/LA Workspace
441+
442+
**Output of the custom PowerShell script**
443+
The script is verbose and will output the steps as it executes.
444+
- It will display the summary, which contains the information about the existing OMS/LA alerts in the workspace and the Azure action groups to be created for the actions associated with them.
445+
- User will be prompted to go ahead with the extension or exit after viewing the summary.
446+
- If the user prompts to go ahead with extension, new Azure action groups will be created and all the existing alerts will be associated with them.
447+
- In the end, the script exits by displaying the message "Extension complete!." In case of any intermediate failures, subsequent errors will be displayed.
448+
449+
## Troubleshooting
450+
During the process of extending alerts from OMS into Azure, there can be occasional issue that prevents the system from creating necessary [Action Groups](monitoring-action-groups.md). In such cases an error message will be shown in OMS portal via banner in Alert section and in GET call done to API.
451+
452+
> [!WARNING]
453+
> If user doesn't take the precribed remediation steps provided below, before **July 5, 2018** - then alerts will run in Azure but without firing any action or notification. To get notifications for alerts, users must manually edit and add [Action Groups](monitoring-action-groups.md) or use the [custom PowerShell script](#option-3---using-custom-powershell-script) provided above.
454+
455+
Listed below are the remediation steps for each error:
456+
1. **Error: Scope Lock is present at subscription/resource group level for write operations**:
227457
![OMS portal Alert Settings page with ScopeLock Error message](./media/monitor-alerts-extend/ErrorScopeLock.png)
228458

229-
a. When Scope Lock is enabled, any new change in subscription or resource group containing the Log Analytics workspace is restricted. The service is unable to migrate alerts to Azure Alerts and create the required action groups.
459+
a. When Scope Lock is enabled, restricting any new change in subscription or resource group containing the Log Analytics (OMS) workspace; the system is unable to extend (copy) alerts into Azure and create necessary action groups.
230460

231-
b. To resolve this, delete the *ReadOnly* lock on your subscription or resource group containing the workspace from the Azure portal, Powershell, Azure CLI, or API. To learn more, review the article [resource lock usage](../azure-resource-manager/resource-group-lock-resources.md).
461+
b. To resolve, delete the *ReadOnly* lock on your subscription or resource group containing the workspace; using Azure portal, Powershell, Azure CLI, or API. To learn more, view the article on [resource lock usage](../azure-resource-manager/resource-group-lock-resources.md).
232462

233-
c. Once you have completed the steps to remove the lock, you can reattempt to migrate your alerts to Azure Alerts within the next day's scheduled run without the need of any action or initiation.
234-
235-
3. **Error: Policy is present at subscription/resource group level**:
463+
c. Once resolved as per steps illustrated in the article, OMS will extend your alerts into Azure within the next day's scheduled run; without the need of any action or initiation.
236464

465+
2. **Error: Policy is present at subscription/resource group level**:
237466
![OMS portal Alert Settings page with Policy Error message](./media/monitor-alerts-extend/ErrorPolicy.png)
238467

239-
a. When [Azure Policy](../azure-policy/azure-policy-introduction.md) is applied, any new resource in subscription or resource group containing the Log Analytics (OMS) workspace is restricted. The service is unable to migrate your alerts into Azure Alerts and create the required action groups.
468+
a. When [Azure Policy](../azure-policy/azure-policy-introduction.md) is applied, restricting any new resource in subscription or resource group containing the Log Analytics (OMS) workspace; the system is unable to extend (copy) alerts into Azure and create necessary action groups.
240469

241-
b. To resolve this, edit the policy causing *[RequestDisallowedByPolicy](../azure-resource-manager/resource-manager-policy-requestdisallowedbypolicy-error.md)* error, which prevents creation of new resources in your subscription or resource group containing the workspace. Using Azure portal, Powershell, Azure CLI or API, you can audit actions to find the appropriate policy causing this failure. To learn more, review the article [viewing activity logs to audit actions](../azure-resource-manager/resource-group-audit.md).
470+
b. To resolve, edit the policy causing *[RequestDisallowedByPolicy](../azure-resource-manager/resource-manager-policy-requestdisallowedbypolicy-error.md)* error, which prevents creation of new resources on your subscription or resource group containing the workspace. Using Azure portal, Powershell, Azure CLI or API; you can audit actions to find the appropriate policy causing failure. To learn more, view the article on [viewing activity logs to audit actions](../azure-resource-manager/resource-group-audit.md).
242471

243-
c. Once you have completed the steps to remove the restriction, Log Analytics will migrate your alerts to Azure Alerts within the next day's scheduled run without the need of any action or initiation.
472+
c. Once resolved as per steps illustrated in the article, OMS will extend your alerts into Azure within the next day's scheduled run; without the need of any action or initiation.
473+
244474

245475
## Next steps
246476

0 commit comments

Comments
 (0)