Gerenciar recursos do Application Insights usando o PowerShell

Artigo
10/18/2023

Nota

Recomendamos que utilize o módulo do Azure Az PowerShell para interagir com o Azure. Veja Instalar o Azure PowerShell para começar. Para saber como migrar para o módulo do Az PowerShell, veja Migrar o Azure PowerShell do AzureRM para o Az.

Este artigo mostra como automatizar a criação e a atualização de recursos do Application Insights automaticamente usando o Azure Resource Manager. Você pode, por exemplo, fazê-lo como parte de um processo de compilação. Junto com o recurso básico do Application Insights, você pode criar testes da Web de disponibilidade, configurar alertas, definir o esquema de preços e criar outros recursos do Azure.

A chave para criar esses recursos são os modelos JSON para o Gerenciador de Recursos. O procedimento básico é:

Faça o download das definições JSON dos recursos existentes.
Parametrizar determinados valores, como nomes.
Execute o modelo sempre que quiser criar um novo recurso.

Você pode empacotar vários recursos juntos para criá-los todos de uma só vez. Por exemplo, você pode criar um monitor de aplicativo com testes de disponibilidade, alertas e armazenamento para exportação contínua. Existem algumas sutilezas em algumas das parametrizações, que explicaremos aqui.

Configuração única

Se você não tiver usado o PowerShell com sua assinatura do Azure antes, instale o módulo do Azure PowerShell na máquina onde deseja executar os scripts:

Instale o Microsoft Web Platform Installer (v5 ou superior).
Use-o para instalar o Azure PowerShell.

Além de usar modelos do Azure Resource Manager (modelos ARM), há um conjunto avançado de cmdlets do PowerShell do Application Insights. Esses cmdlets facilitam a configuração programática dos recursos do Application Insights. Você pode usar os recursos habilitados pelos cmdlets para:

Crie e exclua recursos do Application Insights.
Obtenha listas de recursos do Application Insights e suas propriedades.
Crie e gerencie a exportação contínua.
Crie e gerencie chaves de aplicativo.
Defina a tampa diária.
Defina o plano de preços.

Criar recursos do Application Insights usando um cmdlet do PowerShell

Veja como criar um novo recurso do Application Insights no datacenter do Azure East US usando o cmdlet New-AzApplicationInsights :

New-AzApplicationInsights -ResourceGroupName <resource group> -Name <resource name> -location eastus

Criar recursos do Application Insights usando um modelo ARM

Veja como criar um novo recurso do Application Insights usando um modelo ARM.

Criar o modelo ARM

Crie um novo arquivo .json. Vamos chamá-lo template1.json neste exemplo. Copie este conteúdo para ele:

    {
        "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
        "contentVersion": "1.0.0.0",
        "parameters": {
            "appName": {
                "type": "string",
                "metadata": {
                    "description": "Enter the name of your Application Insights resource."
                }
            },
            "appType": {
                "type": "string",
                "defaultValue": "web",
                "allowedValues": [
                    "web",
                    "java",
                    "other"
                ],
                "metadata": {
                    "description": "Enter the type of the monitored application."
                }
            },
            "appLocation": {
                "type": "string",
                "defaultValue": "eastus",
                "metadata": {
                    "description": "Enter the location of your Application Insights resource."
                }
            },
            "retentionInDays": {
                "type": "int",
                "defaultValue": 90,
                "allowedValues": [
                    30,
                    60,
                    90,
                    120,
                    180,
                    270,
                    365,
                    550,
                    730
                ],
                "metadata": {
                    "description": "Data retention in days"
                }
            },
            "ImmediatePurgeDataOn30Days": {
                "type": "bool",
                "defaultValue": false,
                "metadata": {
                    "description": "If set to true when changing retention to 30 days, older data will be immediately deleted. Use this with extreme caution. This only applies when retention is being set to 30 days."
                }
            },
            "priceCode": {
                "type": "int",
                "defaultValue": 1,
                "allowedValues": [
                    1,
                    2
                ],
                "metadata": {
                    "description": "Pricing plan: 1 = Per GB (or legacy Basic plan), 2 = Per Node (legacy Enterprise plan)"
                }
            },
            "dailyQuota": {
                "type": "int",
                "defaultValue": 100,
                "minValue": 1,
                "metadata": {
                    "description": "Enter daily quota in GB."
                }
            },
            "dailyQuotaResetTime": {
                "type": "int",
                "defaultValue": 0,
                "metadata": {
                    "description": "Enter daily quota reset hour in UTC (0 to 23). Values outside the range will get a random reset hour."
                }
            },
            "warningThreshold": {
                "type": "int",
                "defaultValue": 90,
                "minValue": 1,
                "maxValue": 100,
                "metadata": {
                    "description": "Enter the % value of daily quota after which warning mail to be sent. "
                }
            }
        },
        "variables": {
            "priceArray": [
                "Basic",
                "Application Insights Enterprise"
            ],
            "pricePlan": "[take(variables('priceArray'),parameters('priceCode'))]",
            "billingplan": "[concat(parameters('appName'),'/', variables('pricePlan')[0])]"
        },
        "resources": [
            {
                "type": "microsoft.insights/components",
                "kind": "[parameters('appType')]",
                "name": "[parameters('appName')]",
                "apiVersion": "2014-04-01",
                "location": "[parameters('appLocation')]",
                "tags": {},
                "properties": {
                    "ApplicationId": "[parameters('appName')]",
                    "retentionInDays": "[parameters('retentionInDays')]",
                    "ImmediatePurgeDataOn30Days": "[parameters('ImmediatePurgeDataOn30Days')]"
                },
                "dependsOn": []
            },
            {
                "name": "[variables('billingplan')]",
                "type": "microsoft.insights/components/CurrentBillingFeatures",
                "location": "[parameters('appLocation')]",
                "apiVersion": "2015-05-01",
                "dependsOn": [
                    "[resourceId('microsoft.insights/components', parameters('appName'))]"
                ],
                "properties": {
                    "CurrentBillingFeatures": "[variables('pricePlan')]",
                    "DataVolumeCap": {
                        "Cap": "[parameters('dailyQuota')]",
                        "WarningThreshold": "[parameters('warningThreshold')]",
                        "ResetTime": "[parameters('dailyQuotaResetTime')]"
                    }
                }
            }
        ]
    }

Usar o modelo ARM para criar um novo recurso do Application Insights

No PowerShell, entre no Azure usando $Connect-AzAccounto .
Defina seu contexto para uma assinatura com Set-AzContext "<subscription ID>"o .
Execute uma nova implantação para criar um novo recurso do Application Insights:
```
    New-AzResourceGroupDeployment -ResourceGroupName Fabrikam `
           -TemplateFile .\template1.json `
           -appName myNewApp
```
- -ResourceGroupName é o grupo onde você deseja criar os novos recursos.
- -TemplateFile deve ocorrer antes dos parâmetros personalizados.
- -appName é o nome do recurso a ser criado.

Você pode adicionar outros parâmetros. Você encontrará suas descrições na seção de parâmetros do modelo.

Obter a chave de instrumentação

Depois de criar um recurso de aplicativo, você desejará a chave de instrumentação:

Entre no Azure usando $Connect-AzAccounto .
Defina seu contexto para uma assinatura com Set-AzContext "<subscription ID>"o .
Em seguida, utilize:
1. $resource = Get-AzResource -Name "<resource name>" -ResourceType "Microsoft.Insights/components"
2. $details = Get-AzResource -ResourceId $resource.ResourceId
3. $details.Properties.InstrumentationKey

Para ver uma lista de muitas outras propriedades do seu recurso do Application Insights, use:

Get-AzApplicationInsights -ResourceGroupName Fabrikam -Name FabrikamProd | Format-List

Mais propriedades estão disponíveis por meio dos cmdlets:

Set-AzApplicationInsightsDailyCap
Set-AzApplicationInsightsPricingPlan
Get-AzApplicationInsightsApiKey
Get-AzApplicationInsightsContinuousExport

Consulte a documentação detalhada para obter os parâmetros desses cmdlets.

Nota

A 31 de março de 2025, o suporte da ingestão de chaves de instrumentação terminará. A ingestão de chaves de instrumentação continuará a funcionar, mas não forneceremos mais atualizações ou suporte para o recurso. Transição para cadeias de conexão para aproveitar os novos recursos.

Definir a retenção de dados

Você pode usar os três métodos a seguir para definir programaticamente a retenção de dados em um recurso do Application Insights.

Definir a retenção de dados usando comandos do PowerShell

Aqui está um conjunto simples de comandos do PowerShell para definir a retenção de dados para seu recurso do Application Insights:

$Resource = Get-AzResource -ResourceType Microsoft.Insights/components -ResourceGroupName MyResourceGroupName -ResourceName MyResourceName
$Resource.Properties.RetentionInDays = 365
$Resource | Set-AzResource -Force

Definir a retenção de dados usando REST

Para obter a retenção de dados atual para seu recurso do Application Insights, você pode usar a ferramenta OSS ARMClient. Saiba mais sobre a ARMClient a partir de artigos de David Ebbo e Daniel Bowbyes. Aqui está um exemplo que usa ARMClient para obter a retenção atual:

armclient GET /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName?api-version=2018-05-01-preview

Para definir a retenção, o comando é um PUT semelhante:

armclient PUT /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName?api-version=2018-05-01-preview "{location: 'eastus', properties: {'retentionInDays': 365}}"

Para definir a retenção de dados para 365 dias usando o modelo anterior, execute:

New-AzResourceGroupDeployment -ResourceGroupName "<resource group>" `
       -TemplateFile .\template1.json `
       -retentionInDays 365 `
       -appName myApp

Definir a retenção de dados usando um script do PowerShell

O script a seguir também pode ser usado para alterar a retenção. Copie este script para salvá-lo como Set-ApplicationInsightsRetention.ps1.

Param(
    [Parameter(Mandatory = $True)]
    [string]$SubscriptionId,

    [Parameter(Mandatory = $True)]
    [string]$ResourceGroupName,

    [Parameter(Mandatory = $True)]
    [string]$Name,

    [Parameter(Mandatory = $True)]
    [string]$RetentionInDays
)
$ErrorActionPreference = 'Stop'
if (-not (Get-Module Az.Accounts)) {
    Import-Module Az.Accounts
}
$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
if (-not $azProfile.Accounts.Count) {
    Write-Error "Ensure you have logged in before calling this function."    
}
$currentAzureContext = Get-AzContext
$profileClient = New-Object Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient($azProfile)
$token = $profileClient.AcquireAccessToken($currentAzureContext.Tenant.TenantId)
$UserToken = $token.AccessToken
$RequestUri = "https://management.azure.com/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.Insights/components/$($Name)?api-version=2015-05-01"
$Headers = @{
    "Authorization"         = "Bearer $UserToken"
    "x-ms-client-tenant-id" = $currentAzureContext.Tenant.TenantId
}
## Get Component object via ARM
$GetResponse = Invoke-RestMethod -Method "GET" -Uri $RequestUri -Headers $Headers 

## Update RetentionInDays property
if($($GetResponse.properties | Get-Member "RetentionInDays"))
{
    $GetResponse.properties.RetentionInDays = $RetentionInDays
}
else
{
    $GetResponse.properties | Add-Member -Type NoteProperty -Name "RetentionInDays" -Value $RetentionInDays
}
## Upsert Component object via ARM
$PutResponse = Invoke-RestMethod -Method "PUT" -Uri "$($RequestUri)" -Headers $Headers -Body $($GetResponse | ConvertTo-Json) -ContentType "application/json"
$PutResponse

Este script pode então ser usado como:

Set-ApplicationInsightsRetention `
        [-SubscriptionId] <String> `
        [-ResourceGroupName] <String> `
        [-Name] <String> `
        [-RetentionInDays <Int>]

Defina a tampa diária

Para obter as propriedades de limite diário, use o cmdlet Set-AzApplicationInsightsPricingPlan :

Set-AzApplicationInsightsDailyCap -ResourceGroupName <resource group> -Name <resource name> | Format-List

Para definir as propriedades de limite diário, use o mesmo cmdlet. Por exemplo, para definir o limite para 300 GB por dia:

Set-AzApplicationInsightsDailyCap -ResourceGroupName <resource group> -Name <resource name> -DailyCapGB 300

Você também pode usar o ARMClient para obter e definir parâmetros de limite diários. Para obter os valores atuais, use:

armclient GET /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName/CurrentBillingFeatures?api-version=2018-05-01-preview

Definir o tempo de reposição do limite máximo diário

Para definir o tempo de reposição do limite diário, pode utilizar o ARMClient. Aqui está um exemplo de uso para definir o tempo de ARMClient redefinição para uma nova hora. Este exemplo mostra 12:00 UTC:

armclient PUT /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName/CurrentBillingFeatures?api-version=2018-05-01-preview "{'CurrentBillingFeatures':['Basic'],'DataVolumeCap':{'Cap':100,'WarningThreshold':80,'ResetTime':12}}"

Definir o plano de preços

Para obter o plano de preços atual, use o cmdlet Set-AzApplicationInsightsPricingPlan :

Set-AzApplicationInsightsPricingPlan -ResourceGroupName <resource group> -Name <resource name> | Format-List

Para definir o plano de preços, use o mesmo cmdlet com o -PricingPlan especificado:

Set-AzApplicationInsightsPricingPlan -ResourceGroupName <resource group> -Name <resource name> -PricingPlan Basic

Você também pode definir o plano de preços em um recurso existente do Application Insights usando o modelo ARM anterior, omitindo o recurso "microsoft.insights/components" e o dependsOn nó do recurso de cobrança. Por exemplo, para defini-lo para o plano Por GB (anteriormente chamado de plano Básico), execute:

        New-AzResourceGroupDeployment -ResourceGroupName "<resource group>" `
               -TemplateFile .\template1.json `
               -priceCode 1 `
               -appName myApp

O priceCode é definido como:

priceCode	Planear
1	Por GB (anteriormente chamado de plano Básico)
2	Por nó (anteriormente nomeia o plano Enterprise)

Finalmente, você pode usar o ARMClient para obter e definir planos de preços e parâmetros de limite diário. Para obter os valores atuais, use:

armclient GET /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName/CurrentBillingFeatures?api-version=2018-05-01-preview

Você pode definir todos esses parâmetros usando:

armclient PUT /subscriptions/00000000-0000-0000-0000-00000000000/resourceGroups/MyResourceGroupName/providers/microsoft.insights/components/MyResourceName/CurrentBillingFeatures?api-version=2018-05-01-preview
"{'CurrentBillingFeatures':['Basic'],'DataVolumeCap':{'Cap':200,'ResetTime':12,'StopSendNotificationWhenHitCap':true,'WarningThreshold':90,'StopSendNotificationWhenHitThreshold':true}}"

Este código irá definir o limite diário para 200 GB por dia, configurar o tempo de reposição do limite diário para as 12:00 UTC, enviar e-mails quando o limite for atingido e o nível de aviso for atingido e definir o limiar de aviso para 90% do limite.

Adicionar um alerta de métrica

Para automatizar a criação de alertas métricos, consulte o artigo Modelo de alertas métricos.

Adicionar um teste de disponibilidade

Para automatizar os testes de disponibilidade, consulte o artigo Modelo de alertas métricos.

Adicionar mais recursos

Para automatizar a criação de qualquer outro recurso de qualquer tipo, crie um exemplo manualmente e, em seguida, copie e parametrize seu código do Gerenciador de Recursos do Azure.

Abra o Azure Resource Manager. Navegue até subscriptions/resourceGroups/<your resource group>/providers/Microsoft.Insights/components o recurso do aplicativo.

Os componentes são os recursos básicos do Application Insights para exibir aplicativos. Há recursos separados para as regras de alerta associadas e testes da Web de disponibilidade.
Copie o JSON do componente para o local apropriado em template1.json.
Exclua estas propriedades:
- id
- InstrumentationKey
- CreationDate
- TenantId
Abra as webtests seções e e alertrules copie o JSON para itens individuais em seu modelo. Não copie dos webtests nós ou alertrules . Vá para os itens sob eles.

Cada teste da Web tem uma regra de alerta associada, portanto, você tem que copiar ambos.
Insira esta linha em cada recurso:

"apiVersion": "2015-05-01",

Parametrizar o modelo

Agora você tem que substituir os nomes específicos por parâmetros. Para parametrizar um modelo, você escreve expressões usando um conjunto de funções auxiliares.

Você não pode parametrizar apenas parte de uma cadeia de caracteres, portanto, use concat() para criar cadeias de caracteres.

Aqui estão exemplos das substituições que você vai querer fazer. Há várias ocorrências de cada substituição. Você pode precisar de outras pessoas em seu modelo. Esses exemplos usam os parâmetros e variáveis que definimos na parte superior do modelo.

Localizar	Replace with
`"hidden-link:/subscriptions/.../../components/MyAppName"`	`"[concat('hidden-link:',` `resourceId('microsoft.insights/components',` `parameters('appName')))]"`
`"/subscriptions/.../../alertrules/myAlertName-myAppName-subsId",`	`"[resourceId('Microsoft.Insights/alertrules', variables('alertRuleName'))]",`
`"/subscriptions/.../../webtests/myTestName-myAppName",`	`"[resourceId('Microsoft.Insights/webtests', parameters('webTestName'))]",`
`"myWebTest-myAppName"`	`"[variables(testName)]"'`
`"myTestName-myAppName-subsId"`	`"[variables('alertRuleName')]"`
`"myAppName"`	`"[parameters('appName')]"`
`"myappname"` (minúsculas)	`"[toLower(parameters('appName'))]"`
`"<WebTest Name=\"myWebTest\" ...` `Url=\"http://fabrikam.com/home\" ...>"`	`[concat('<WebTest Name=\"',` `parameters('webTestName'),` `'\" ... Url=\"', parameters('Url'),` `'\"...>')]"`

Definir dependências entre os recursos

O Azure deve configurar os recursos em ordem estrita. Para garantir que uma configuração seja concluída antes que a próxima comece, adicione linhas de dependência:

No recurso de teste de disponibilidade:

"dependsOn": ["[resourceId('Microsoft.Insights/components', parameters('appName'))]"],
No recurso de alerta para um teste de disponibilidade:

"dependsOn": ["[resourceId('Microsoft.Insights/webtests', variables('testName'))]"],

Próximos passos

Veja estes outros artigos de automação:

Criar um recurso do Application Insights
Crie testes web.
Envie o Diagnóstico do Azure para o Application Insights.
Crie anotações de versão.