Insights de lançamento e item de trabalho

O Azure Pipelines integra-se com o Application Insights para permitir o monitoramento contínuo do pipeline de lançamento do Azure DevOps durante todo o ciclo de vida de desenvolvimento de software.

Com o monitoramento contínuo, os pipelines de liberação podem incorporar dados de monitoramento do Application Insights e de outros recursos do Azure. Quando o pipeline de liberação deteta um alerta do Application Insights, o pipeline pode bloquear ou reverter a implantação até que o alerta seja resolvido. Se todas as verificações forem aprovadas, as implantações podem prosseguir automaticamente do teste até a produção, sem a necessidade de intervenção manual.

Configurar monitoramento contínuo

1. No Azure DevOps, selecione uma organização e um projeto.

2. No menu esquerdo da página do projeto, selecione Pipelines>Releases.

3. Selecione a seta suspensa ao lado de Novo e selecione Novo pipeline de versão. Ou, se você ainda não tiver um pipeline, selecione Novo pipeline na página exibida.

4. No painel Selecionar um modelo, procure e selecione Implantação do Serviço de Aplicativo do Azure com monitoramento contínuo e selecione Aplicar.

   

5. Na caixa Estágio 1, selecione o hiperlink para Exibir tarefas do palco.

   

6. No painel de configuração do Estágio 1 , preencha os seguintes campos:

   Parâmetro	Value
   Nome artístico	Forneça um nome artístico ou deixe-o no Estágio 1.
   Subscrição do Azure	Selecione a seta suspensa e selecione a assinatura vinculada do Azure que você deseja usar.
   Tipo de aplicação	Selecione a seta suspensa e selecione seu tipo de aplicativo.
   Nome do Serviço de Aplicativo	Insira o nome do seu Serviço de Aplicativo do Azure.
   Nome do grupo de recursos para o Application Insights	Selecione a seta suspensa e selecione o grupo de recursos que deseja usar.
   Nome do recurso do Application Insights	Selecione a seta suspensa e selecione o recurso do Application Insights para o grupo de recursos selecionado.

7. Para salvar o pipeline com as configurações de regra de alerta padrão, selecione Salvar no canto superior direito da janela do Azure DevOps. Insira um comentário descritivo e selecione OK.

Modificar regras de alerta

Pronta para uso, a implantação do Serviço de Aplicativo do Azure com modelo de monitoramento contínuo tem quatro regras de alerta: Disponibilidade, Solicitações com falha, Tempo de resposta do servidor e Exceções do servidor. Você pode adicionar mais regras ou alterar as configurações de regras para atender às suas necessidades de nível de serviço.

Para modificar as configurações da regra de alerta:

No painel esquerdo da página do pipeline de versão, selecione Configurar alertas do Application Insights.

As quatro regras de alerta padrão são criadas por meio de um script Inline:

$subscription = az account show --query "id";$subscription.Trim("`"");$resource="/subscriptions/$subscription/resourcegroups/"+"$(Parameters.AppInsightsResourceGroupName)"+"/providers/microsoft.insights/components/" + "$(Parameters.ApplicationInsightsResourceName)";
az monitor metrics alert create -n 'Availability_$(Release.DefinitionName)' -g $(Parameters.AppInsightsResourceGroupName) --scopes $resource --condition 'avg availabilityResults/availabilityPercentage < 99' --description "created from Azure DevOps";
az monitor metrics alert create -n 'FailedRequests_$(Release.DefinitionName)' -g $(Parameters.AppInsightsResourceGroupName) --scopes $resource --condition 'count requests/failed > 5' --description "created from Azure DevOps";
az monitor metrics alert create -n 'ServerResponseTime_$(Release.DefinitionName)' -g $(Parameters.AppInsightsResourceGroupName) --scopes $resource --condition 'avg requests/duration > 5' --description "created from Azure DevOps";
az monitor metrics alert create -n 'ServerExceptions_$(Release.DefinitionName)' -g $(Parameters.AppInsightsResourceGroupName) --scopes $resource --condition 'count exceptions/server > 5' --description "created from Azure DevOps";

Você pode modificar o script e adicionar mais regras de alerta. Você também pode modificar as condições de alerta. E você pode remover regras de alerta que não fazem sentido para seus fins de implantação.

Adicionar condições de implantação

Quando você adiciona portas de implantação ao pipeline de lançamento, um alerta que excede os limites definidos impede a promoção de lançamento indesejado. Depois de resolver o alerta, a implantação pode prosseguir automaticamente.

Para adicionar portas de implantação:

1. Na página principal do pipeline, em Estágios, selecione o símbolo Condições de pré-implantação ou Condições pós-implantação, dependendo de qual estágio precisa de uma porta de monitoramento contínuo.

   

2. No painel de configuração de condições de pré-implantação, defina Gates como Enabled.

3. Ao lado de Portões de implantação, selecione Adicionar.

4. Selecione Consultar alertas do Azure Monitor no menu suspenso. Essa opção permite acessar alertas do Azure Monitor e do Application Insights.

   

5. Em Opções de avaliação, insira os valores desejados para configurações como O tempo entre a reavaliação de portas e O tempo limite após o qual as portas falham.

Ver registos de lançamento

Você pode ver o comportamento do portão de implantação e outras etapas de liberação nos logs de versão. Para abrir os registos:

1. Selecione Liberações no menu esquerdo da página do pipeline.

2. Selecione qualquer versão.

3. Em Estágios, selecione qualquer estágio para exibir um resumo da versão.

4. Para exibir logs, selecione Exibir logs no resumo da versão, selecione o hiperlink Bem-sucedido ou Reprovado em qualquer estágio ou passe o mouse sobre qualquer estágio e selecione Logs.

   

As anotações mostram onde você implantou uma nova compilação ou outros eventos significativos. As anotações facilitam a visualização se as alterações tiveram algum efeito no desempenho do aplicativo. Eles podem ser criados automaticamente pelo sistema de compilação do Azure Pipelines . Você também pode criar anotações para sinalizar qualquer evento desejado criando-as a partir do PowerShell.

Anotações de lançamento com a compilação do Azure Pipelines

As anotações de versão são um recurso do serviço Azure Pipelines baseado em nuvem do Azure DevOps.

Se todos os critérios a seguir forem atendidos, a tarefa de implantação criará a anotação de versão automaticamente:

• O recurso ao qual você está implantando está vinculado ao Application Insights por meio da configuração do APPINSIGHTS_INSTRUMENTATIONKEY aplicativo.

• O recurso do Application Insights está na mesma assinatura que o recurso no qual você está implantando.

• Você está usando uma das seguintes tarefas de pipeline do Azure DevOps:

  Código da tarefa	Nome da tarefa	Versões
  AzureAppServiceSettings	Configurações do Serviço de Aplicativo do Azure	Qualquer
  AzureRmWebAppDeployment	Implantação do Serviço de Aplicativo do Azure	V3 e superior
  AzureFunctionApp	Funções do Azure	Qualquer
  AzureFunctionAppContainer	Azure Functions para contêiner	Qualquer
  AzureWebAppContainer	Aplicativo Web do Azure para contêineres	Qualquer
  AzureWebApp	Aplicação Web do Azure	Qualquer

Configurar anotações de versão

Se você não puder usar uma das tarefas de implantação na seção anterior, precisará adicionar uma tarefa de script embutido em seu pipeline de implantação.

1. Vá para um pipeline novo ou existente e selecione uma tarefa.

   

2. Adicione uma nova tarefa e selecione CLI do Azure.

   

3. Especifique a assinatura relevante do Azure. Altere Tipo de Script para PowerShell e Local do Script para Inline.

4. Adicione o script do PowerShell da etapa 2 na próxima seção ao Script embutido.

5. Adicione os seguintes argumentos. Substitua os espaços reservados entre colchetes angulares por seus valores para Argumentos de Script. Os -releaseProperties são opcionais.

       -aiResourceId "<aiResourceId>" `
       -releaseName "<releaseName>" `
       -releaseProperties @{"ReleaseDescription"="<a description>";
            "TriggerBy"="<Your name>" }
   

   

   O exemplo a seguir mostra metadados que você pode definir no argumento opcional releaseProperties usando variáveis build e release .

   -releaseProperties @{
    "BuildNumber"="$(Build.BuildNumber)";
    "BuildRepositoryName"="$(Build.Repository.Name)";
    "BuildRepositoryProvider"="$(Build.Repository.Provider)";
    "ReleaseDefinitionName"="$(Build.DefinitionName)";
    "ReleaseDescription"="Triggered by $(Build.DefinitionName) $(Build.BuildNumber)";
    "ReleaseEnvironmentName"="$(Release.EnvironmentName)";
    "ReleaseId"="$(Release.ReleaseId)";
    "ReleaseName"="$(Release.ReleaseName)";
    "ReleaseRequestedFor"="$(Release.RequestedFor)";
    "ReleaseWebUrl"="$(Release.ReleaseWebUrl)";
    "SourceBranch"="$(Build.SourceBranch)";
    "TeamFoundationCollectionUri"="$(System.TeamFoundationCollectionUri)" }
   

6. Selecione Guardar.

Criar anotações de versão com a CLI do Azure

Você pode usar o script do PowerShell para criar anotações de qualquer processo desejado sem usar o CreateReleaseAnnotation Azure DevOps.

1. Entre na CLI do Azure.

2. Faça uma cópia local do script a seguir e chame-o CreateReleaseAnnotation.ps1de .

   param(
       [parameter(Mandatory = $true)][string]$aiResourceId,
       [parameter(Mandatory = $true)][string]$releaseName,
       [parameter(Mandatory = $false)]$releaseProperties = @()
   )
   
   # Function to ensure all Unicode characters in a JSON string are properly escaped
   function Convert-UnicodeToEscapeHex {
     param (
       [parameter(Mandatory = $true)][string]$JsonString
     )
     $JsonObject = ConvertFrom-Json -InputObject $JsonString
     foreach ($property in $JsonObject.PSObject.Properties) {
       $name = $property.Name
       $value = $property.Value
       if ($value -is [string]) {
         $value = [regex]::Unescape($value)
         $OutputString = ""
         foreach ($char in $value.ToCharArray()) {
           $dec = [int]$char
           if ($dec -gt 127) {
             $hex = [convert]::ToString($dec, 16)
             $hex = $hex.PadLeft(4, '0')
             $OutputString += "\u$hex"
           }
           else {
             $OutputString += $char
           }
         }
         $JsonObject.$name = $OutputString
       }
     }
     return ConvertTo-Json -InputObject $JsonObject -Compress
   }
   
   $annotation = @{
       Id = [GUID]::NewGuid();
       AnnotationName = $releaseName;
       EventTime = (Get-Date).ToUniversalTime().GetDateTimeFormats("s")[0];
       Category = "Deployment"; #Application Insights only displays annotations from the "Deployment" Category
       Properties = ConvertTo-Json $releaseProperties -Compress
   }
   
   $annotation = ConvertTo-Json $annotation -Compress
   $annotation = Convert-UnicodeToEscapeHex -JsonString $annotation  
   
   $accessToken = (az account get-access-token | ConvertFrom-Json).accessToken
   $headers = @{
       "Authorization" = "Bearer $accessToken"
       "Accept"        = "application/json"
       "Content-Type"  = "application/json"
   }
   $params = @{
       Headers = $headers
       Method  = "Put"
       Uri     = "https://management.azure.com$($aiResourceId)/Annotations?api-version=2015-05-01"
       Body    = $annotation
   }
   Invoke-RestMethod @params
   

   Nota

   • Suas anotações devem ter Categoria definida como Implantação para aparecer no portal do Azure.
   • Se você receber um erro, "A solicitação contém um corpo de entidade, mas nenhum cabeçalho Content-Type", tente remover os parâmetros de substituição na linha a seguir.

   $body = (ConvertTo-Json $annotation -Compress)

3. Chame o script do PowerShell com o código a seguir. Substitua os espaços reservados entre colchetes angulares pelos seus valores. Os -releaseProperties são opcionais.

        .\CreateReleaseAnnotation.ps1 `
         -aiResourceId "<aiResourceId>" `
         -releaseName "<releaseName>" `
         -releaseProperties @{"ReleaseDescription"="<a description>";
             "TriggerBy"="<Your name>" }
   

   Argumento	Definição	Nota
   aiResourceId	O ID do recurso para o recurso de destino do Application Insights.	Exemplo: /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/MyRGName/providers/microsoft.insights/components/MyResourceName
   releaseName	O nome para dar a anotação de versão criada.
   releaseProperties	Usado para anexar metadados personalizados à anotação.	Opcional

Ver anotações

Sempre que você usa o modelo de versão para implantar uma nova versão, uma anotação é enviada para o Application Insights. Você pode exibir anotações nos seguintes locais:

• Desempenho:

  

• Falhas:

  

• Utilização:

  

• Pastas de trabalho:

  Em qualquer consulta de pasta de trabalho baseada em log em que a visualização exiba o tempo ao longo do eixo x:

  

Para habilitar anotações em sua pasta de trabalho, vá para Configurações avançadas e selecione Mostrar anotações.

Selecione qualquer marcador de anotação para abrir detalhes sobre a versão, incluindo solicitante, ramificação de controle do código-fonte, pipeline de liberação e ambiente.

Liberar anotações usando chaves de API

As anotações de versão são um recurso do serviço Azure Pipelines baseado em nuvem do Azure DevOps.

Instalar a extensão de anotações (uma vez)

Para criar anotações de versão, instale uma das muitas extensões do Azure DevOps disponíveis no Visual Studio Marketplace.

1. Entre no seu projeto de DevOps do Azure.

2. Na página de extensão Visual Studio Marketplace Release Annotations, selecione sua organização do Azure DevOps. Selecione Instalar para adicionar a extensão à sua organização do Azure DevOps.

   

Você só precisa instalar a extensão uma vez para sua organização do Azure DevOps. Agora você pode configurar anotações de versão para qualquer projeto em sua organização.

Configurar anotações de versão usando chaves de API

Crie uma chave de API separada para cada um dos seus modelos de versão do Azure Pipelines.

1. Entre no portal do Azure e abra o recurso do Application Insights que monitora seu aplicativo. Ou, se você não tiver um, crie um novo recurso do Application Insights.

2. Abra a guia Acesso à API e copie o ID do Application Insights.

   

3. Em uma janela separada do navegador, abra ou crie o modelo de versão que gerencia suas implantações do Azure Pipelines.

4. Selecione Adicionar tarefa e, em seguida, selecione a tarefa Anotação de versão do Application Insights no menu.

   

   Nota

   Atualmente, a tarefa Anotação de Versão suporta apenas agentes baseados no Windows. Ele não será executado em Linux, macOS ou outros tipos de agentes.

5. Em ID do aplicativo, cole o ID do Application Insights copiado da guia Acesso à API.

   

6. De volta à janela Acesso à API do Application Insights, selecione Criar chave de API.

   

7. Na janela Criar chave de API, insira uma descrição, selecione Gravar anotações e, em seguida, selecione Gerar chave. Copie a nova chave.

   

8. Na janela do modelo de versão, na guia Variáveis , selecione Adicionar para criar uma definição de variável para a nova chave de API.

9. Em Nome, digite ApiKey. Em Valor, cole a chave da API copiada da guia Acesso à API.

   

10. Selecione Salvar na janela principal do modelo de versão para salvar o modelo.

    Nota

    Os limites para chaves de API são descritos na documentação de limites de taxa de API REST.

Transição para a nova anotação de versão

Para usar as novas anotações de versão:

1. Remova a extensão Release Annotations.
2. Remova a tarefa Anotação de Versão do Application Insights em sua implantação do Azure Pipelines.
3. Crie novas anotações de versão com o Azure Pipelines ou a CLI do Azure.

A funcionalidade de integração de item de trabalho permite que você crie facilmente itens de trabalho no GitHub ou no Azure DevOps que tenham dados relevantes do Application Insights incorporados neles.

A nova integração de itens de trabalho oferece os seguintes recursos em relação ao clássico:

• Campos avançados como cessionário, projetos ou marcos.
• Ícones de repositório para que você possa diferenciar entre pastas de trabalho do GitHub e do Azure DevOps.
• Várias configurações para qualquer número de repositórios ou itens de trabalho.
• Implantação por meio de modelos do Azure Resource Manager.
• Consultas pré-criadas ou personalizáveis da Keyword Query Language (KQL) para adicionar dados do Application Insights aos seus itens de trabalho.
• Modelos de pasta de trabalho personalizáveis.

Criar e configurar um modelo de item de trabalho

1. Para criar um modelo de item de trabalho, vá para o recurso do Application Insights e, à esquerda, em Configurar , selecione Itens de Trabalho e, na parte superior, selecione Criar um novo modelo

   

   Você também pode criar um modelo de item de trabalho na guia de detalhes da transação de ponta a ponta, se nenhum modelo existir no momento. Selecione um evento e, à direita, selecione Criar um item de trabalho e, em seguida, Iniciar com um modelo de pasta de trabalho.

   

2. Depois de selecionar criar um novo modelo, você pode escolher seus sistemas de rastreamento, nomear sua pasta de trabalho, vincular ao sistema de acompanhamento selecionado e escolher uma região para armazenar o modelo (o padrão é a região em que o recurso do Application Insights está localizado). Os parâmetros de URL são a URL padrão para seu repositório, por exemplo, https://github.com/myusername/reponame ou https://dev.azure.com/{org}/{project}.

   

   Você pode definir propriedades específicas do item de trabalho diretamente do próprio modelo. Isso inclui o cessionário, caminho de iteração, projetos, & mais, dependendo do seu provedor de controle de versão.

   Nota

   Para ambientes de DevOps do Azure locais, uma URL de exemplo, como https://dev.azure.com/test/test pode ser usada como um espaço reservado para a URL do Projeto de DevOps do Azure. Depois que o modelo de item de trabalho for criado, você poderá modificar a URL e sua regra de validação na pasta de trabalho do Azure gerada.

Criar um item de trabalho

Você pode acessar seu novo modelo a partir de qualquer detalhe de transação de ponta a ponta que possa acessar em Desempenho, Falhas, Disponibilidade ou outras guias.

1. Para criar um item de trabalho, vá para Detalhes da transação de ponta a ponta, selecione um evento e, em seguida, selecione Criar item de trabalho e escolha seu modelo de item de trabalho.

   

2. Uma nova guia no seu navegador será aberta para o seu sistema de rastreamento selecionado. No Azure DevOps você pode criar um bug ou tarefa, e no GitHub você pode criar um novo problema em seu repositório. Um novo item de trabalho é criado automaticamente com informações contextuais fornecidas pelo Application Insights.

   

   

Editar um modelo

Para editar seu modelo, vá para a guia Itens de Trabalho em Configurar e selecione o ícone de lápis ao lado da pasta de trabalho que você deseja atualizar.

Selecione editar na barra de ferramentas superior.

Você pode criar mais de uma configuração de item de trabalho e ter uma pasta de trabalho personalizada para atender a cada cenário. As pastas de trabalho também podem ser implantadas pelo Azure Resource Manager, garantindo implementações padrão em seus ambientes.

Integração clássica de itens de trabalho

1. No recurso do Application Insights, em Configurar , selecione Itens de Trabalho.

2. Selecione Mudar para Clássico, preencha os campos com as suas informações e autorize.

   

3. Crie um item de trabalho indo para os detalhes da transação de ponta a ponta, selecione um evento e selecione Criar item de trabalho (Clássico).

Migrar para nova integração de item de trabalho

Para migrar, exclua sua configuração clássica de item de trabalho e, em seguida , crie e configure um modelo de item de trabalho para recriar sua integração.

Para excluir, vá para, no recurso do Application Insights, em Configurar , selecione Itens de Trabalho , selecione Alternar para Clássico e *Excluir na parte superior.