Administración de recursos de Application Insights mediante PowerShell

Artículo
09/12/2023

Nota

Se recomienda usar el módulo Azure Az de PowerShell para interactuar con Azure. Consulte Instalación de Azure PowerShell para empezar. Para más información sobre cómo migrar al módulo Az de PowerShell, consulte Migración de Azure PowerShell de AzureRM a Az.

Este artículo muestra cómo automatizar la creación y actualización de los recursos de Application Insights automáticamente mediante Azure Resource Manager. Puede hacerlo, por ejemplo, como parte de un proceso de compilación. Junto con el recurso básico de Application Insights, puede crear pruebas web de disponibilidad, configurar alertas, establecer el esquema de precios y crear otros recursos de Azure.

La clave para crear estos recursos son las plantillas JSON para Resource Manager. El procedimiento básico es el siguiente:

Descargue las definiciones JSON de los recursos existentes.
Parametrice determinados valores, como nombres.
Ejecute la plantilla siempre que quiera crear un nuevo recurso.

Puede empaquetar varios recursos juntos para crearlos todos en un solo uso. Por ejemplo, puede crear un monitor de aplicaciones con pruebas de disponibilidad, alertas y almacenamiento para la exportación continua. Existen algunos matices a algunas de las parametrizaciones automáticas, que se explican aquí.

Instalación única

Si no ha usado PowerShell con la suscripción de Azure antes, instale el módulo Azure PowerShell en el equipo en el que desea ejecutar los scripts:

Instale el Instalador de plataforma web de Microsoft (v5 o superior).
Úselo para instalar Azure PowerShell.

Además de usar plantillas de Azure Resource Manager (plantillas de ARM), hay un amplio conjunto de cmdlets de PowerShell de Application Insights. Estos cmdlets facilitan la configuración de recursos de Application Insights mediante programación. Puede usar las funcionalidades habilitadas por los cmdlets para:

Crear y eliminar recursos de Application Insights.
Obtener listas de recursos de Application Insights y sus propiedades.
Crear y administrar la exportación continua.
Crear y administrar claves de aplicación.
Establecer el límite diario.
Consultar el plan de precios

Creación de recursos de Application Insights mediante un cmdlet de PowerShell

Aquí se muestra cómo crear un nuevo recurso de Application Insights en el centro de datos Este de EE. UU. de Azure con el cmdlet New-AzApplicationInsights:

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

Creación de recursos de Application Insights mediante una plantilla de ARM

A continuación se muestra cómo crear un nuevo recurso de Application Insights mediante una plantilla de ARM.

Creación de la plantilla de Resource Manager

Cree un archivo .json. Vamos a llamarlo template1.json en este ejemplo. Copie este contenido en él:

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

Uso de la plantilla de ARM para crear un nuevo recurso de Application Insights

En PowerShell, inicie sesión en Azure mediante $Connect-AzAccount.
Establezca el contexto en una suscripción con Set-AzContext "<subscription ID>".
Ejecute una nueva implementación para crear un nuevo recurso de Application Insights:
```
    New-AzResourceGroupDeployment -ResourceGroupName Fabrikam `
           -TemplateFile .\template1.json `
           -appName myNewApp
```
- -ResourceGroupName es el grupo donde desea crear los nuevos recursos.
- -TemplateFile debe aparecer antes que los parámetros personalizados.
- -appName es el nombre del recurso que se va a crear.

Puede agregar otros parámetros. Puede ver las descripciones en la sección de parámetros de la plantilla.

Obtención de la clave de instrumentación

Después de crear un recurso de aplicación, querrá la clave de instrumentación:

Inicio de sesión en Azure mediante $Connect-AzAccount.
Establezca el contexto en una suscripción con Set-AzContext "<subscription ID>".
Después, 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 una lista de muchas otras propiedades del recurso de Application Insights, use el siguiente comando:

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

Dispone de propiedades adicionales a través de los siguientes cmdlets:

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

Consulte la documentación detallada para información sobre los parámetros de estos cmdlets.

Nota

El 31 de marzo de 2025 finalizará la compatibilidad con la ingesta de claves de instrumentación. La ingesta de claves de instrumentación seguirá funcionando, pero la característica ya no recibirá actualizaciones ni soporte técnico. Transición a las cadenas de conexión para aprovechar las nuevas funcionalidades.

Establecimiento de la retención de datos

Puede usar los siguientes tres métodos para establecer la retención de datos mediante programación en un recurso de Application Insights.

Establecimiento de la retención de datos mediante comandos de PowerShell

A continuación se muestra un conjunto sencillo de comandos de PowerShell para establecer la retención de datos para el recurso de Application Insights:

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

Establecimiento de la retención de datos mediante REST

Para obtener la retención actual de datos del recurso de Application Insights, puede usar la herramienta OSS ARMClient Obtenga más información sobre ARMClient en los artículos de David Ebbo y Daniel Bowbyes. Este es un ejemplo que usa ARMClient para obtener la retención actual:

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

Para establecer la retención, se usa un comando PUT similar:

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 establecer la retención de datos en 365 días mediante la plantilla anterior, ejecute:

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

Establecimiento de la retención de datos mediante un script de PowerShell

El siguiente script también se puede usar para cambiar la retención. Copie este script para guardarlo 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

Después, este script se puede utilizar para:

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

Establecimiento del límite diario

Para obtener las propiedades de límite diario, use el cmdlet Set-AzApplicationInsightsPricingPlan:

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

Para establecer las propiedades de límite diario, use el mismo cmdlet. Por ejemplo, para establecer el límite en 300 GB/día:

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

También puede usar ARMClient para obtener y establecer parámetros de límite diarios. Para obtener los valores actuales, use:

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

Establecimiento del tiempo de restablecimiento del límite diario

Para establecer el tiempo de restablecimiento del límite diario, puede usar ARMClient. Este es un ejemplo de uso de ARMClient para establecer el tiempo de restablecimiento en una hora nueva. En este ejemplo se muestran las 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}}"

Establecimiento del plan de precios

Para obtener el plan de precios actual, use el cmdlet Set-AzApplicationInsightsPricingPlan:

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

Para establecer el plan de precios, use el mismo cmdlet con la especificación de -PricingPlan:

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

También puede establecer el plan de precios de un recurso de Application Insights existente mediante la plantilla de ARM anterior, omitiendo el recurso "microsoft.insights/components" y el nodo dependsOn del recurso de facturación. Por ejemplo, para establecerlo en el plan Por GB (antes plan Básico), ejecute:

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

priceCode se define como:

priceCode	Plan
1	Por GB (anteriormente denominado plan Básico)
2	Por nodo (anteriormente denominado plan Enterprise)

Por último, puede usar ARMClient para obtener y establecer planes de precios y parámetros de límite diarios. Para obtener los valores actuales, use:

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

Puede establecer todos estos parámetros mediante:

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 establecerá el límite diario en 200 GB/día, configurará el tiempo de restablecimiento del límite diario en 12:00 UTC, enviará mensajes de correo electrónico cuando se alcance el límite y se cumpla el nivel de advertencia, y establecerá el umbral de advertencia en el 90 % del límite.

Agregar una alerta de métrica

Para automatizar la creación de las alertas de métricas, consulte el artículo sobre la plantilla de alertas de métricas.

Agregar una prueba de disponibilidad

Para automatizar las pruebas de disponibilidad, consulte el artículo sobre la plantilla de alertas de métricas.

Agregar más recursos

Para automatizar la creación de otros recursos de cualquier variante, cree un ejemplo manualmente y luego copie y parametrice su código en Azure Resource Manager.

Abra el Administrador de recursos de Azure. Desplácese hacia abajo por subscriptions/resourceGroups/<your resource group>/providers/Microsoft.Insights/components hasta el recurso de la aplicación.

Componentes son los recursos básicos de Application Insights para mostrar aplicaciones. Existen recursos distintos para las reglas de alerta asociadas y las pruebas web de disponibilidad.
Copie el código JSON del componente en el lugar adecuado en template1.json.
Elimine estas propiedades:
- id
- InstrumentationKey
- CreationDate
- TenantId
Abra las secciones webtests y alertrules y copie el código JSON de los elementos individuales en la plantilla. No copie desde los nodos webtests o alertrules. Vaya a los elementos debajo de ellos.

Cada prueba web tiene una regla de alerta asociada, por lo que tiene que copiar las dos.
Inserte esta línea en cada recurso:

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

Parametrización de la plantilla

Ahora, debe reemplazar los nombres específicos por parámetros. Para parametrizar una plantilla, escriba expresiones mediante un conjunto de funciones auxiliares.

No se puede parametrizar solo una parte de una cadena, así que use concat() para compilar las cadenas.

Éstos son ejemplos de sustituciones que querrá realizar. Hay varias repeticiones de cada sustitución. Y puede que tenga otras en la plantilla. En estos ejemplos se usan los parámetros y las variables que se han definido en la parte superior de la plantilla.

Buscar	Reemplazar 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'),` `'\"...>')]"`

Establecimiento de dependencias entre los recursos

Azure debe instalar los recursos en un orden estricto. Para tener la seguridad de que una instalación finaliza antes de que comience la siguiente, agregue líneas de dependencia:

En el recurso de la prueba de disponibilidad:

"dependsOn": ["[resourceId('Microsoft.Insights/components', parameters('appName'))]"],
En el recurso de la alerta para una prueba de disponibilidad:

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

Pasos siguientes

Consulte estos otros artículos de automatización: