在 Azure Spring Apps 中使用 Application Insights Java 进程内代理

项目
10/30/2024

注意

基本、标准和企业计划将从 2025 年 3 月中旬开始弃用，停用期为 3 年。建议转换到 Azure 容器应用。有关详细信息，请参阅 Azure Spring Apps 停用公告。

标准消耗和专用计划将于 2024 年 9 月 30 日开始弃用，并在六个月后完全关闭。建议转换到 Azure 容器应用。

使用 Spring Boot 本机映像应用程序时，请在 Spring Boot 本机映像 Java 应用程序中使用 Azure Monitor OpenTelemetry Distro/ Application Insights 项目，而不是 Application Insights Java 代理。

本文介绍如何在 Azure Spring Apps 中使用 Application Insights Java 代理来监视应用程序。

使用此功能，你可以：

通过不同的筛选器搜索跟踪数据。
查看 Spring 应用程序的依赖关系映射。
检查请求性能。
监视实时指标。
检查请求失败。
检查应用程序指标。
检查应用程序日志。

Application Insights 提供许多可观察的视角，包括：

应用程序映射
性能
失败
指标
实时指标
可用性
日志

使用 Application Insights 功能

启用 Application Insights 功能后，你可以：

在导航窗格中，选择“Application Insights”以查看 Application Insights 的“概述”页。 “概述”页显示所有正在运行的应用程序的概述。
选择“应用程序映射”以查看在应用程序之间进行的调用的状态。
选择客户服务与 petclinic 之间的链接以查看更多详细信息，例如 SQL 查询。
选择一个终结点，以查看所有对该终结点发出请求的应用程序。
在导航窗格中，选择“性能”以查看所有应用程序的操作的性能数据、依赖项和角色。
在导航窗格中，选择“失败”以查看应用程序发生的任何意外失败或异常。
在导航窗格中，选择“指标”并选择命名空间，以查看 Spring Boot 指标和自定义指标（如果有）。
在导航窗格中，选择“实时指标”以查看不同维度的实时指标。
在导航窗格中，选择“可用性”以通过创建 Application Insights 中的可用性测试来监视 Web 应用的可用性和响应能力。
在导航窗格中，选择“日志”以查看所有应用程序的日志，或按 cloud_RoleName 筛选某一个应用程序的日志。

使用 Azure 门户管理 Application Insights

使用以下过程启用 Java 进程内代理。

转到服务实例的“服务 | 概述”页，然后在“监视”部分选择“Application Insights”。
选择“启用 Application Insights”以在 Azure Spring Apps 中启用 Application Insights。
选择 Application Insights 的一个现有实例，或者创建一个新实例。
启用“Application Insights”后，可以配置一个可选采样率（默认值为 10.0%）。
选择“保存”以保存更改。

备注

请不要在不同的 Azure Spring Apps 实例中使用同一个 Application Insights 实例，否则会看到混合的数据。

使用 Azure CLI 管理 Application Insights

可以使用 Azure CLI 命令管理 Application Insights。在以下命令中，请务必将 <placeholder> 文本替换为所述的值。 <service-instance-name> 占位符表示 Azure Spring Apps 实例的名称。

启用 Application Insights

若要在创建 Azure Spring Apps 实例时配置 Application Insights，请使用以下命令。对于 app-insights 参数，可以指定 Application Insights 名称或资源 ID。

az spring create \
    --resource-group <resource-group-name> \
    --name "service-instance-name" \
    --app-insights <name-or-resource-ID> \
    --sampling-rate <sampling-rate>

还可以使用 Application Insights 连接字符串（首选）或检测密钥，如以下示例中所示。

az spring create \
    --resource-group <resource-group-name> \
    --name <service-instance-name> \
    --app-insights-key <connection-string-or-instrumentation-key> \
    --sampling-rate <sampling-rate>

禁用 Application Insights

若要在创建 Azure Spring Apps 实例时禁用 Application Insights，请使用以下命令：

az spring create \
    --resource-group <resource-group-name> \
    --name <service-instance-name> \
    --disable-app-insights

检查 Application Insights 设置

若要检查现有 Azure Spring Apps 实例的 Application Insights 设置，请使用以下命令：

az spring app-insights show \
    --resource-group <resource-group-name> \
    --name <service-instance-name>

更新 Application Insights

若要将 Application Insights 更新为使用连接字符串（首选）或检测密钥，请使用以下命令：

az spring app-insights update \
    --resource-group <resource-group-name> \
    --name <service-instance-name> \
    --app-insights-key <connection-string-or-instrumentation-key> \
    --sampling-rate <sampling-rate>

若要将 Application Insights 更新为使用资源名称或 ID，请使用以下命令：

az spring app-insights update \
    --resource-group <resource-group-name> \
    --name <service-instance-name> \
    --app-insights <name-or-resource-ID> \
    --sampling-rate <sampling-rate>

使用 update 命令禁用 Application Insights

若要在现有 Azure Spring Apps 实例上禁用 Application Insights，请使用以下命令：

az spring app-insights update \
    --resource-group <resource-group-name> \
    --name <service-instance-name> \
    --disable

自动化

以下部分介绍如何使用 Bicep、Azure 资源管理器模板（ARM 模板）或 Terraform 自动完成部署。

Bicep

若要使用 Bicep 文件进行部署，请将以下内容复制到 main.bicep 文件中。有关详细信息，请参阅 Microsoft.AppPlatform Spring/monitoringSettings。

param springName string
param location string = resourceGroup().location

resource spring 'Microsoft.AppPlatform/Spring@2020-07-01' = {
  name: springName
  location: location
  properties: {}
}

resource monitorSetting 'Microsoft.AppPlatform/Spring/monitoringSettings@2020-11-01-preview' = {
  parent: spring
  name: 'default'
  properties: {
    appInsightsInstrumentationKey: '00000000-0000-0000-0000-000000000000'
    appInsightsSamplingRate: 88
  }
}

ARM 模板

若要使用 ARM 模板进行部署，请将以下内容复制到 azuredeploy.json 文件中。有关详细信息，请参阅 Microsoft.AppPlatform Spring/monitoringSettings。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "springName": {
      "type": "string"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.AppPlatform/Spring",
      "apiVersion": "2020-07-01",
      "name": "[parameters('springName')]",
      "location": "[parameters('location')]",
      "properties": {}
    },
    {
      "type": "Microsoft.AppPlatform/Spring/monitoringSettings",
      "apiVersion": "2020-11-01-preview",
      "name": "[format('{0}/{1}', parameters('springName'), 'default')]",
      "properties": {
        "appInsightsInstrumentationKey": "00000000-0000-0000-0000-000000000000",
        "appInsightsSamplingRate": 88
      },
      "dependsOn": [
        "[resourceId('Microsoft.AppPlatform/Spring', parameters('springName'))]"
      ]
    }
  ]
}

Terraform

对于 Terraform 部署，请使用以下模板。有关详细信息，请参阅 azurerm_spring_cloud_service。

provider "azurerm" {
  features {}
}

resource "azurerm_resource_group" "example" {
  name     = "example-resources"
  location = "China North 2"
}

resource "azurerm_application_insights" "example" {
  name                = "tf-test-appinsights"
  location            = azurerm_resource_group.example.location
  resource_group_name = azurerm_resource_group.example.name
  application_type    = "web"
}

resource "azurerm_spring_cloud_service" "example" {
  name                = "example-springcloud"
  resource_group_name = azurerm_resource_group.example.name
  location            = azurerm_resource_group.example.location
  sku_name            = "S0"

  config_server_git_setting {
    uri          = "https://github.com/Azure-Samples/piggymetrics"
    label        = "config"
    search_paths = ["dir1", "dir2"]
  }

  trace {
    connection_string = azurerm_application_insights.example.connection_string
    sample_rate       = 10.0
  }

  tags = {
    Env = "staging"
  }
}

Java 代理更新/升级

Java 代理会随 JDK 一起定期更新/升级，这可能会影响以下方案。

注意

JDK 版本每年每季度更新/升级一次。

更新/升级之前使用 Java 代理的现有应用程序不会受到影响。
更新/升级后创建的应用程序使用新版 Java 代理。
以前未使用 Java 代理的现有应用程序需要重启或重新部署，然后才能使用新版 Java 代理。

Java 代理配置热加载

Azure Spring Apps 采用一种热加载机制来调整代理配置的设置，而无需重启应用程序。

注意

热加载机制有几分钟延迟时间。

如果已启用了 Java 代理，则更改 Application Insights 实例或 SamplingRate 值不要求重启应用程序。
如果启用 Java 代理，则必须重启应用程序。
禁用 Java 代理后，应用程序会在几分钟的延迟后停止发送所有监视数据。你可以重启应用程序以从 Java 运行时环境中删除代理。

Azure Spring Apps 和 Application Insights 之间的概念匹配

Azure Spring Apps	Application Insights
`App`	* 应用程序映射/角色 * 实时指标/角色 * 故障/角色/云角色 * 性能/角色/云角色
`App Instance`	* 应用程序映射/角色实例 * 实时指标/服务名称 * 故障/角色/云实例 * 性能/角色/云实例

Azure Spring Apps 中的名称 App Instance 会在以下情况下更改或生成：

创建新的应用程序。
将 JAR 文件或源代码部署到现有应用程序。
启动蓝/绿部署。
重启应用程序。
停止部署应用程序，然后重新启动应用程序。

如果数据存储在 Application Insights 中，它将包含自启用 Java 代理后创建或部署的 Azure Spring Apps 应用实例的历史记录。例如，在 Application Insights 门户中，可以看到昨天创建的应用程序数据，但这些数据会在特定时间范围内删除，例如最近的 24 小时。以下场景展示了此过程：

今天上午 8:00 左右，你在启用 Java 代理的情况下在 Azure Spring Apps 中创建了一个应用程序，然后在今天上午 8:10 左右将 JAR 文件部署至该应用程序。在进行一些测试后，你更改了代码，并在今天上午 8:30 将新的 JAR 文件部署至该应用程序。然后你休息了一会儿，并在上午 11:00 回来检查 Application Insights 中的部分数据。可看到：
- 应用程序映射中的三个实例（时间范围为过去 24 小时）以及“失败”、“性能”和“指标”。
- 应用程序映射中的一个实例（时间范围为过去 1 小时）以及“失败”、“性能”和“指标”。
- 实时指标中的一个实例。
今天上午 8:00 左右，你在启用 Java 代理的情况下在 Azure Spring Apps 中创建了一个应用程序，然后在今天上午 8:10 左右将 JAR 文件部署至该应用程序。在今天上午 8:30 左右，你使用另一个 JAR 文件尝试了一次蓝/绿部署。目前，此应用程序有两个部署。休息到上午 11:00 后，你想要查看 Application Insights 中的某些数据。可看到：
- 应用程序映射中的三个实例（时间范围为过去 24 小时）以及“失败”、“性能”和“指标”。
- 应用程序映射中的两个实例（时间范围为过去 1 小时）以及“失败”、“性能”和“指标”。
- 实时指标中的两个实例。

通过