你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

发布和工作项见解

项目
11/15/2023

发布和工作项见解对于优化软件开发生命周期至关重要。随着应用程序的发展，密切监视每个发布及其工作项至关重要。这些见解突出显示了性能瓶颈，让团队能够主动解决问题，确保实现顺畅的部署和用户体验。它们有助于开发人员和利益干系人做出决策、调整流程并交付高质量的软件。

Azure Pipelines 与 Application Insights 集成，可以在整个软件开发生命周期内持续监视 Azure DevOps 发布管道。

借助持续监视，发布管道可以结合来自 Application Insights 和其他 Azure 资源的监视数据。当发布管道检测到 Application Insights 警报时，该管道可以限制或回滚部署，直到警报已解决。如果所有检查都通过，可以从测试到生产全程自动执行部署，无需手动干预。

配置连续监视

在 Azure DevOps 中选择一个组织和项目。
在项目页的左菜单中，选择“管道”>“发布”。
选择“新建”旁边的下拉箭头，然后选择“新建发布管道”。如果你没有管道，请在显示的页面上选择“新建管道”。
在“选择模板”窗格中，搜索并选择“支持持续监视的 Azure 应用服务部署”，然后选择“应用”。
在“阶段 1”框中，选择“查看阶段任务”超链接。

在“阶段 1”配置窗格中填写以下字段：

参数	Value
阶段名称	提供阶段名称，或将其保留为“阶段 1”。
Azure 订阅	选择下拉箭头并选择要使用的关联 Azure 订阅。
应用类型	选择下拉箭头，然后选择你的应用类型。
应用服务名称	输入 Azure 应用服务的名称。
Application Insights 的资源组名称	选择下拉箭头并选择要使用的资源组。
Application Insights 资源名称	选择下拉箭头并选择所选资源组的 Application Insights 资源。

若要使用默认的警报规则设置保存管道，请在“Azure DevOps”窗口的右上角选择“保存”。输入描述性的注释，然后选择“确定”。

修改警报规则

现成的“支持持续监视的 Azure 应用服务部署”模板包含四个警报规则：“可用性”、“失败的请求”、“服务器响应时间”和“服务器异常”。可以添加更多规则，或根据服务级别需求更改规则设置。

若要修改警报规则设置：

在发布管道页的左窗格中，选择“配置 Application Insights 警报”。

四个默认警报规则是通过内联脚本创建的：

$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";

你可以修改脚本并添加更多警报规则。你还可以修改警报条件。并且可以删除对部署目的没有意义的警报规则。

添加部署条件

将部署门限添加到发布管道时，会出现一条指出超过了设置的阈值的警报，此警报旨在防止不需要的发布升级。在你解决此警报后，部署可自动继续进行。

若要添加部署门限：

在管道主页上的“阶段”下，根据哪个阶段需要持续监视门限，选择“部署前的条件”或“部署后的条件”符号。
在“部署前的条件”配置窗格中，将“门限”设置为“已启用”。
在“部署门限”的旁边，选择“添加”。
从下拉菜单中选择“查询 Azure Monitor 警报”。使用此选项可以访问 Azure Monitor 和 Application Insights 警报。
在“评估选项”下，输入要对“重新评估门限的间隔时间”和“门限失败之前所要经过的超时”等设置使用的值。

查看发布日志

可以在发布日志中查看部署门限行为和其他发布步骤。若要打开日志：

从管道页的左菜单中选择“发布”。
选择任一发布活动。
在“阶段”下，选择任一阶段以查看发布摘要。
若要查看日志，请在发布摘要中选择“查看日志”，然后在任一阶段中选择“成功”或“失败”超链接，或者将鼠标悬停在任一阶段上并选择“日志”。

注释显示将新版本部署到了何处，或者显示其他重要事件。使用批注可让轻松查看更改是否对应用程序的性能产生了任何影响。 Azure Pipelines 生成系统可自动创建批注。也可以通过 PowerShell 创建注释，用于标记所要处理的任何事件。

Azure Pipelines 生成中的版本批注

版本批注是 Azure DevOps 的基于云的 Azure Pipelines 服务功能。

如果满足以下所有条件，部署任务会自动创建发布注释：

要部署到的资源通过 APPINSIGHTS_INSTRUMENTATIONKEY 应用设置链接到 Application Insights。
Application Insights 资源与要部署到的资源位于同一订阅中。

你使用的是以下 Azure DevOps 管道任务之一：

任务代码	任务名称	版本
AzureAppServiceSettings	Azure 应用服务设置	任意
AzureRmWebAppDeployment	Azure 应用服务部署	V3 和更高版本
AzureFunctionApp	Azure Functions	任意
AzureFunctionAppContainer	适用于容器的 Azure Functions	任意
AzureWebAppContainer	用于容器的 Azure Web 应用	任意
AzureWebApp	Azure Web 应用	任意

注意

如果仍在使用 Application Insights 注释部署任务，则应将其删除。

配置版本批注

如果无法使用上一部分中的部署任务，则需要在部署管道中添加内联脚本任务。

转到新的或现有的管道，然后选择一项任务。
添加一个新任务，然后选择“Azure CLI”。
指定相关的 Azure 订阅。将“脚本类型”更改为“PowerShell”，将“脚本位置”更改为“内联”。
将下一节中步骤 2 中的 PowerShell 脚本添加到内联脚本。

添加以下参数。将带尖括号的占位符替换为你的“脚本参数”值。 -releaseProperties 是可选的。

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

以下示例显示了可以使用 build 和 release 变量在可选的 releaseProperties 参数中设置的元数据。

-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)" }

选择“保存”。

使用 Azure CLI 创建发布注释

可以使用 CreateReleaseAnnotation PowerShell 脚本根据所需的任何流程创建注释，而无需使用 Azure DevOps。

创建以下脚本的本地副本并将其命名为 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  

$body = $annotation -replace '(\\+)"', '$1$1"' -replace "`"", "`"`""

az rest --method put --uri "$($aiResourceId)/Annotations?api-version=2015-05-01" --body "$($body) "

# Use the following command for Linux Azure DevOps Hosts or other PowerShell scenarios
# Invoke-AzRestMethod -Path "$aiResourceId/Annotations?api-version=2015-05-01" -Method PUT -Payload $body

注意

你的注释必须将“类别”设置为“部署”才能显示在 Azure 门户中。
如果收到“请求包含实体正文，但不包含 Content-Type 标头”错误，请尝试删除以下行中的替换参数。

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

使用以下代码调用 PowerShell 脚本。将带尖括号的占位符替换为你的值。 -releaseProperties 是可选的。

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

参数	定义	注意
`aiResourceId`	目标 Application Insights 资源的资源 ID。	示例： /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MyRGName/providers/microsoft.insights/components/MyResourceName
`releaseName`	为创建的版本注释提供的名称。
`releaseProperties`	用于将自定义元数据附加到注释。	可选

查看批注

注意

发布注释目前在 Application Insights 的“指标”窗格中不可用。

每当你使用发布模板部署新版本时，系统就会将注释发送到 Application Insights。可以在以下位置查看注释：

性能：
失败：
用法：
工作簿：

在任何基于日志的工作簿查询中，可视化效果沿 x 轴显示时间：

要在工作簿中启用注释，请转到“高级设置”，然后选择“显示注释”。

Screenshot that shows the Advanced Settings menu with the show annotations checkbox highlighted.

选择任一注释标记可打开有关该发布的详细信息，包括请求者、源代码管理分支、发布管道和环境。

使用 API 密钥的发布注释

版本批注是 Azure DevOps 的基于云的 Azure Pipelines 服务功能。

重要

使用 API 密钥的批注已弃用。建议改为使用 Azure CLI。

安装注释扩展（一次性操作）

若要创建发布注释，请安装 Visual Studio Marketplace 中提供的多个 Azure DevOps 扩展中的一个。

登录到 Azure DevOps 项目。
在 Visual Studio Marketplace“发布注释扩展”页上，选择 Azure DevOps 组织。选择“安装”，将扩展添加到 Azure DevOps 组织。

只需为 Azure DevOps 组织安装该扩展一次。现在，可为组织中的任何项目配置版本批注。

使用 API 密钥配置发布注释

为每个 Azure Pipelines 发布模板单独创建一个 API 密钥。

登录到 Azure 门户并打开负责监视应用程序的 Application Insights 资源。或者，如果你没有，请创建一个新的 Application Insights 资源。
打开“API 访问”选项卡并复制 Application Insights ID。
在另一个浏览器窗口中，打开或创建用于管理 Azure Pipelines 部署的发布模板。
添加“添加任务”，然后从菜单中选择“Application Insights 发布注释”任务。

注意

“发布注释”任务当前仅支持基于 Windows 的代理。它不会在 Linux、macOS 或其他类型的代理上运行。
在“应用程序 ID”下，粘贴从“API 访问”选项卡复制的 Application Insights ID。
返回 Application Insights 的“API 访问”窗口，选择“创建 API 密钥”。
在“创建 API 密钥”窗口中，输入说明，选择“编写注释”，然后选择“生成密钥”。复制新密钥。
在“发布模板”窗口中的“变量”选项卡上，选择“添加”以创建新 API 密钥的变量定义。
在“名称”下，输入 ApiKey。在“值”下，粘贴从“API 访问”选项卡复制的 API 密钥。
在“发布模板”主窗口中选择“保存”以保存模板。

注意

API 密钥的限制在 REST API 速率限制文档中进行了说明。

转换到新的发布注释

要使用新的发布注释，请参阅以下文章：

删除发布注释扩展。
删除 Azure Pipelines 部署中的 Application Insights 发布注释任务。
使用 Azure Pipelines 或 Azure CLI 创建新的发布注释。

使用工作项集成功能，你可以轻松地在 GitHub 或 Azure DevOps 中创建工作项，并在其中嵌入相关的 Application Insights 数据。

新的工作项集成提供经典版所不具备的以下功能：

被分派人、项目或里程碑等高级字段。
存储库图标，从中可以区分 GitHub 工作簿与 Azure DevOps 工作簿。
任意数量的存储库或工作项的多个配置。
通过 Azure 资源管理器模板进行部署。
预生成的且可自定义的关键字查询语言 (KQL) 查询，可将 Application Insights 数据添加到工作项。
可自定义的工作簿模板。

创建和配置工作项模板

若要创建工作项模板，请转到你的 Application Insights 资源，并在左侧的“配置”下选择“工作项”，然后在顶部选择“创建新模板”。

如果当前不存在任何模板，你还可以通过“端到端事务详细信息”选项卡创建工作项模板。选择一个事件，在右侧选择“创建工作项”，然后选择“从工作簿模板开始”。
选择“创建新模板”后，你可以选择你的跟踪系统，为你的工作簿命名，链接到所选的跟踪系统，并选择用于存储该模板的区域（默认为你的 Application Insights 资源所在的区域）。 URL 参数是你的存储库的默认 URL，例如 https://github.com/myusername/reponame 或 https://dev.azure.com/{org}/{project}。

可以直接从模板本身设置特定工作项属性。这包括被分派人、迭代路径、项目等等，具体取决于你的版本控制提供程序。

创建工作项

你可以从任何可从“性能”、“故障”、“可用性”或其他选项卡访问的“端到端事务详细信息”来访问新模板。

若要创建工作项，请转到“端到端事务详细信息”，选择一个事件，然后选择“创建工作项”并选择你的工作项模板。
浏览器中的一个新选项卡将打开你选择的跟踪系统。在 Azure DevOps 中，你可以创建 bug 或任务，在 GitHub 中，你可以在存储库中创建新问题。将自动创建一个新的工作项，其中包含 Application Insights 提供的上下文信息。