Insights de versão e item de trabalho

O Azure Pipelines está integrado ao Application Insights para fazer o monitoramento contínuo do pipeline de lançamento do Azure DevOps em todo o ciclo de vida de desenvolvimento de software.

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

Configurar o monitoramento contínuo

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

2. No menu à esquerda da página do projeto, selecione Pipelines>Lançamentos.

3. Selecione a seta suspensa ao lado de Novo e selecione Novo pipeline de lançamento. Ou, se você ainda não tem um pipeline, selecione Novo pipeline na página que aparece.

4. No painel Selecione um modelo, pesquise e selecione Implantação do Serviço de Aplicativo do Azure com Monitoramento Contínuo e selecione Aplicar.

   

5. Na caixa Fase 1, selecione o link para Exibir tarefas da fase.

   

6. No painel de configuração da Fase1, preencha os seguintes campos:

   Parâmetro	Valor
   Nome do estágio	Dê um nome à fase ou mantenha o nome Fase 1.
   Assinatura do Azure	Selecione a seta do menu suspenso e, em seguida, a assinatura vinculada do Azure que você deseja usar.
   Tipo de aplicativo	Selecione a seta suspensa e o tipo de aplicativo.
   Nome do Serviço de Aplicativo	Digite o nome do seu Serviço de Aplicativo do Azure.
   Nome do grupo de recursos do Application Insights	Selecione a seta suspensa e o grupo de recursos que você deseja usar.
   Nome do recurso do Application Insights	Selecione a seta suspensa e o recurso do Application Insights para o grupo de recursos que você selecionou.

7. Para salvar o pipeline com as configurações de regra de alerta padrão, selecione Salvar no canto superior direito na janela do Azure DevOps. Insira uma descrição e selecione OK.

Modificar as regras de alerta

O modelo Implantação do Serviço de Aplicativo do Azure com monitoramento contínuo já vem com 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 das regras de acordo com o nível de serviço necessário.

Para modificar as configurações de regras de alerta:

No painel esquerdo da página de pipeline de lançamento, selecione Configurar alertas do Application insights.

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

$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 do alerta. E você pode remover regras de alerta que não fazem sentido para suas finalidades de implantação.

Adicionar condições de implantação

Quando você adiciona portões de implantação ao pipeline de lançamento, um alerta que excede os limites definidos impede a promoção de uma versão indesejada. Após resolver o alerta, a implantação poderá continuar automaticamente.

Para adicionar portões de implantação:

1. Na página principal do pipeline, em Fases, selecione o símbolo Condições de pré-implantação ou Condições pós-implantação, dependendo da fase que precisa de portão de monitoramento.

   

2. No painel de configuração Condições de pré-implantação, defina Portões como Habilitado.

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 os 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 portões e O tempo limite após o qual os portões falham.

Exibir logs de lançamento

Você pode ver o comportamento do portão de implantação e outras etapas de lançamento nos logs de versões. Para abrir os logs:

1. Selecione Versões no menu à esquerda da página pipeline.

2. Selecione qualquer versão.

3. Em Fases, selecione uma fase para exibir um resumo da versão.

4. Para ver logs, selecione Exibir logs no resumo de versão, selecione o link Êxito ou Falha de uma fase ou passe o mouse sobre uma fase e selecione Logs.

   

As anotações mostram em que local um novo build foi implantado ou demais eventos significativos. As anotações facilitam conferir se as alterações tiveram algum efeito sobre o desempenho do aplicativo. O sistema de build do Azure Pipelines pode criar anotações de modo automático. Você também pode criar anotações para sinalizar eventos desejados criando-as no PowerShell.

Anotações de versão com o build do Azure Pipelines

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

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

• O recurso que você está implantando está vinculado ao Application Insights por meio da configuração APPINSIGHTS_INSTRUMENTATIONKEY do 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 acima
  AzureFunctionApp	Funções do Azure	Qualquer
  AzureFunctionAppContainer	Azure Functions para contêiner	Qualquer
  AzureWebAppContainer	Aplicativo Web para Contêineres do Azure	Qualquer
  AzureWebApp	Aplicativo Web do Azure	Qualquer

Criar 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 ao pipeline de implantação.

1. Navegue até 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 o Tipo de Script para PowerShell e a Localização do Script para Embutido.

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

5. Adicione os seguintes argumentos. Substitua os espaços reservados entre colchetes angulares pelos valores para Argumentos de Script. O -releaseProperties é opcional.

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

   

   Veja abaixo um exemplo de metadados que você pode definir no argumento opcional releaseProperties usando variáveis de build e versão.

   -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 Salvar.

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

É possível usar o script do PowerShellCreateReleaseAnnotation para criar anotações de processos de sua preferência, sem usar o Azure DevOps.

1. Entre na CLI do Azure.

2. Faça uma cópia local do script a seguir e nomeie-o como CreateReleaseAnnotation.ps1.

   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
   

   Observação

   • As anotações devem ter a Categoria definida como Implantação para serem exibidas 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 com colchetes angulares pelos valores. O -releaseProperties é opcional.

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

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

Exibir anotações

Agora, sempre que você usar o modelo de versão para implantar uma versão, uma anotação será enviada ao Application Insights. Você pode exibir anotações nos seguintes locais:

• Desempenho:

  

• Falhas:

  

• Uso:

  

• Workbooks.

  Em consultas de pastas de trabalho baseadas em log em que a visualização exibe o tempo ao longo do eixo x.

  

Para habilitar anotações em sua pasta de trabalho, acesse Configurações Avançadas e selecione Mostrar anotações.

Selecione um marcador de anotação para abrir detalhes sobre a versão, incluindo: o solicitante, o branch de controle do código-fonte, o pipeline de lançamento e o ambiente.

Anotações de versão com chaves de API

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

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

Para criar anotações de versão, será preciso instalar uma das várias extensões do Azure DevOps disponíveis no Visual Studio Marketplace.

1. Entre em seu projeto do Azure DevOps.

2. Na página Visual Studio Marketplace Extensão Ade notações de Versão, selecione sua organização do Azure DevOps. Selecione Instalar para adicionar a extensão à sua organização do Azure DevOps.

   

Será preciso instalar a extensão para sua organização do Azure DevOps somente uma vez. Agora é possível configurar anotações de versão para projetos de sua organização.

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

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

1. Entre no portal do Azure e abra o recurso do Application Insights que monitora seu aplicativo. Caso contrário, crie um recurso do Application Insights.

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

   

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

4. Clique em Adicionar tarefa, depois selecione a tarefa de Anotação de Versão do Application Insights no menu.

   

   Observação

   A tarefa de Anotação de Versão, atualmente, só dá suporte à agentes baseados no Windows. Não funciona no Linux, macOS ou outros tipos de agentes.

5. Na opção ID do Aplicativo, cole a ID do Application Insights copiada da guia Acesso à API.

   

6. Retorne à janela Acesso à API do Application Insights, depois clique em Criar Chave de API.

   

7. Na janela Criar Chave de API, digite uma descrição, selecione Anotações de gravação, depois clique em Gerar chave. Copie a nova chave.

   

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

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

   

10. Clique no botão Salvar da janela principal do modelo de versão para salvar o modelo.

    Observação

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

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

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

1. Remova a extensão de anotações de versão.
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.

Com a funcionalidade de integração de itens de trabalho, você pode criar com facilidade itens de trabalho no GitHub ou no Azure DevOps que têm dados relevantes do Application Insights inseridos neles.

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

• Campos avançados, como destinatá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 KQL (Linguagem de Consulta de Palavra-chave) pré-criadas e personalizáveis para adicionar dados do Application Insights aos seus itens de trabalho.
• Modelos de workbook personalizáveis.

Criar e configurar um modelo de item de trabalho

1. Para criar um modelo de item de trabalho, acesse o Application Insights. À esquerda, em Configurar, selecione Itens de Trabalho e, na parte superior, clique em Criar um modelo

   

   Você também pode criar um modelo de item de trabalho na guia de detalhes de transação de ponta a ponta caso não exista nenhum modelo. Selecione um evento e clique em Criar um item de trabalho, à direita. Depois, escolha Iniciar com um modelo de pasta de trabalho.

   

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

   

   É possível definir propriedades específicas do item de trabalho diretamente no modelo. Dependendo do seu provedor de controle de versão, isso inclui os projetos de atribuição, caminho de iteração, projetos e assim por diante.

   Observação

   Para ambientes locais do Azure DevOps, você pode usar uma URL de exemplo, como https://dev.azure.com/test/test, como um espaço reservado para a URL do Projeto do Azure DevOps. 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

Para acessar o novo modelo nos Detalhes de transação de ponta a ponta, basta clicar nas guias Desempenho, Falhas, Acessibilidade, entre outras.

1. Para criar um item de trabalho, Acesse os Detalhes de transação de ponta a ponta, selecione um evento e clique em Criar item de trabalho. Depois, escolha seu modelo de item de trabalho.

   

2. Será aberta uma nova guia no navegador que levará ao sistema de acompanhamento selecionado. No Azure DevOps, é possível criar um bug ou uma tarefa. No GitHub, você pode criar um problema no repositório. Um novo item de trabalho é criado automaticamente com informações contextuais do Application Insights.

   

   

Editar um modelo

Para editar o modelo, acesse a guia itens de Trabalho, em Configurar, e clique no ícone de lápis ao lado da pasta de trabalho que você deseja atualizar.

Selecione editar na barra de ferramentas na parte superior da página.

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. Também é possível implantar as pastas de trabalho por meio do Azure Resource Manager para garantir implementações padrão nos seus ambientes.

Integração de itens de trabalho clássicos

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

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

   

3. Crie um item de trabalho acessando os detalhes da transação de ponta a ponta, selecione um evento e clique em Criar item de trabalho (clássico) .

Migrar para a nova integração de item de trabalho

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

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