Gerenciar recursos do Application Insights usando o PowerShell

Artigo
10/15/2024

Observação

Recomendamos que você use o módulo Az PowerShell do Azure para interagir com o Azure. Para começar, consulte Instalar o Azure PowerShell. Para saber como migrar para o módulo Az PowerShell, confira Migrar o Azure PowerShell do AzureRM para o Az.

Este artigo mostra como automatizar a criação e atualização de recursos do Application Insights automaticamente usando o Azure Resource Manager. Por exemplo, você pode fazer isso como parte de um processo de compilação. Juntamente com o recurso básico do Application Insights, é possível criar testes na 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 de JSON para o Azure Resource Manager. O procedimento básico é:

Baixe as definições JSON dos recursos existentes.
Parametrizar determinados valores, como nomes.
Execute o modelo sempre que desejar 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 para algumas das parametrizações, que vamos explicar aqui.

Configuração única

Se você nunca usou o PowerShell com sua assinatura do Azure, instale o módulo do Azure PowerShell no computador em que você 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 modelos do ARM ( Azure Resource Manager), há um conjunto avançado de cmdlets do PowerShell do Application Insights. Esses cmdlets facilitam a configuração de recursos do Application Insights de forma programática. Você pode usar os recursos habilitados pelos cmdlets para:

Criar e excluir recursos do Application Insights.
Obter listas de recursos de Application Insights e suas propriedades.
Criar e gerenciar a exportação contínua.
Criar e gerenciar chaves de aplicativo.
Definir o limite diário.
Definir o plano de preços.

Criar recursos do Application Insights usando um cmdlet do PowerShell

Confira como criar um novo recurso de Application Insights no datacenter do Leste dos EUA do Azure usando o cmdlet New-AzApplicationInsights:

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

Criar recursos do Application Insights com um modelo do ARM

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

Criar um modelo do ARM

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

    {
        "$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')]"
                    }
                }
            }
        ]
    }

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

No PowerShell, entre no Azure usando $Connect-AzAccount.
Defina o contexto para uma assinatura com Set-AzContext "<subscription ID>".
Executar uma nova implantação para criar um novo recurso do Application Insights:
```
    New-AzResourceGroupDeployment -ResourceGroupName Fabrikam `
           -TemplateFile .\template1.json `
           -appName myNewApp
```
- -ResourceGroupName é o grupo em que você deseja criar 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

Após criar um recurso de aplicativo, é desejável obter a chave de instrumentação:

Entrar no Azure usando $Connect-AzAccount.
Defina o contexto para uma assinatura com Set-AzContext "<subscription ID>".
Em seguida, use:
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 recurso 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

Confira a documentação detalhada para obter os parâmetros para esses cmdlets.

Observação

Em 31 de março de 31, 2025, o suporte à ingestão de chave de instrumentação será encerrado. A ingestão de chave de instrumentação continuará funcionando, mas não forneceremos mais atualizações ou suporte para o recurso. Transição para cadeias de conexão para aproveitar as novas funcionalidades.

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

Veja um conjunto simples de comandos do PowerShell para definir a retenção de dados para o recurso do Application Insights:

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

Definir retenção de dados usando REST

Para obter a retenção de dados atual do recurso do Application Insights, você pode usar a ferramenta OSS ARMClient. Saiba mais sobre o ARMClient nos artigos de David Ebbo e Daniel Bowbyes. Este é 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 salvar 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

Esse script pode ser usado como:

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

Definir o limite diário

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 como 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ário. Para receber 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 a hora de redefinição do limite diário

Para definir a hora de redefinição do limite diário, você pode usar o ARMClient. Este é um exemplo que usa o ARMClient para definir a hora de redefinição para um novo horário. Este exemplo mostra 12h00 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 do ARM anterior, omitindo o recurso "microsoft.insights/components" e o nó dependsOn do recurso de cobrança. Por exemplo, para defini-lo para o plano por GB (antes chamado de plano Básico), execute:

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

priceCode é definido como:

priceCode	Plano
1	Por GB (antes chamado de plano Básico)
2	Por nó (antes chamado de plano Enterprise)

Por fim, você pode usar o ARMClient para obter e definir planos de preços e parâmetros de limite diário. Para receber 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}}"

Esse código definirá o limite diário de 200 GB por dia, configurará a hora de redefinição do limite diário para 12h00 UTC, enviará emails quando o limite e o nível de aviso forem atingidos e definirá o limite de aviso como 90% do limite.

Adicionar um alerta de Métrica

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

Adicionar um teste de disponibilidade

Para automatizar os testes de disponibilidade, confira o artigo Modelo de alertas de métrica.

Adicionar mais recursos

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

Abra o Gerenciador de Recursos do Azure. Navegar por subscriptions/resourceGroups/<your resource group>/providers/Microsoft.Insights/components até o recurso do aplicativo.

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 no template1.json.
Exclua essas propriedades:
- id
- InstrumentationKey
- CreationDate
- TenantId
Abra as seções webtests e alertrules, depois copie o JSON para itens individuais no seu modelo. Não copie dos nós webtests ou alertrules. Acesse os itens abaixo deles.

Cada teste da web tem uma regra de alerta associada, então você precisa 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, escreva expressões que usam um conjunto de funções auxiliares.

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

Estes são exemplos das substituições que você vai querer fazer. Há várias ocorrências de cada substituição. Talvez seja necessário outras em seu modelo. Esses exemplos usam os parâmetros e variáveis definidos na parte superior do modelo.

Localizar	Substitua por
`"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úscula)	`"[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 na ordem explícita. Para certificar-se de que a instalação é concluída antes do início da próxima, adicione linhas de dependência:

No recurso do 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óximas etapas

Confira este outros artigos sobre automação:

Compartilhar via