Azure 应用服务和 Python 的应用程序监视（预览版）

项目
07/24/2024

重要

有关 beta 版本、预览版或尚未正式发布的版本的 Azure 功能所适用的法律条款，请参阅 Azure 预览版的补充使用条款。

在 Azure 应用服务上监视 Python Web 应用程序，而无需修改代码。本指南介绍如何启用 Azure Monitor Application Insights，并提供自动执行大规模部署的使用技巧。

集成工具在代码中常用的 Python 库，让你可以自动收集和关联依赖项、日志和指标。检测后，从以下 Python 库收集调用和指标：

检测	支持的库名称	支持的版本
OpenTelemetry Django Instrumentation	`django`	link
OpenTelemetry FastApi Instrumentation	`fastapi`	link
OpenTelemetry Flask Instrumentation	`flask`	link
OpenTelemetry Psycopg2 Instrumentation	`psycopg2`	link
OpenTelemetry Requests Instrumentation	`requests`	link
OpenTelemetry UrlLib Instrumentation	`urllib`	全部
OpenTelemetry UrlLib3 Instrumentation	`urllib3`	link

注意

如果使用 Django，请参阅本文中的 Django Instrumentation 附加部分。

日志记录遥测是在根记录器级别收集的。若要详细了解 Python 的本机日志记录层次结构，请访问 Python 日志记录文档。

先决条件

Python 版本 3.11 或更早版本。
应用服务必须部署为代码。不支持自定义容器。

启用 Application Insights

在 Azure 应用服务上监视 Python 应用程序的最简单方法是通过 Azure 门户。

在 Azure 门户中激活监视会自动使用 Application Insights 检测应用程序，无需更改代码。

注意

如果不在代码中使用 OpenTelemetry 的手动检测（例如 Azure Monitor OpenTelemetry 发行版或 Azure Monitor OpenTelemetry 导出器），则应仅在应用服务上使用自动结构。这是为了防止发送重复数据。有关详细信息，请查看本文中的故障排除部分。

通过 Azure 门户进行自动检测

有关支持的自动检测方案的完整列表，请参阅支持的环境、语言和资源提供程序。

在 Azure 应用服务中打开 Python 应用的监视，无需更改代码。

适用于 Python 的 Application Insights 与基于代码的 Linux Azure 应用服务集成。

集成处于公开预览阶段。它添加在正式版中的 Python SDK。

在应用服务的 Azure 控制面板中，选择“Application Insights”，然后选择“启用”。
选择创建新资源，或为此应用程序选择现有 Application Insights 资源。

注意

选择“确定”来创建新资源时，系统将提示你“应用监视设置”。选择“继续”会将新的 Application Insights 资源链接到你的应用服务，这样做还会触发应用服务的重新启动。
请指定资源，它就可供使用了。

配置

可以使用 OpenTelemetry 环境变量进行配置，例如：

环境变量	描述
`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`	指定与应用程序关联的 OpenTelemetry 资源属性。可以使用 OTEL_RESOURCE_ATTRIBUTES 设置任何资源属性，或使用 OTEL_SERVICE_NAME 来仅设置 `service.name`。
`OTEL_LOGS_EXPORTER`	如果设置为 `None`，则禁用日志记录遥测的收集和导出。
`OTEL_METRICS_EXPORTER`	如果设置为 `None`，则禁用指标遥测的收集和导出。
`OTEL_TRACES_EXPORTER`	如果设置为 `None`，则禁用分布式跟踪遥测数据的收集和导出。
`OTEL_BLRP_SCHEDULE_DELAY`	指定日志记录导出间隔（以毫秒为单位）。默认为 5000。
`OTEL_BSP_SCHEDULE_DELAY`	指定分布式跟踪导出间隔（以毫秒为单位）。默认为 5000。
`OTEL_TRACES_SAMPLER_ARG`	指定采样分布式跟踪遥测的比率。接受的值范围为 0 到 1。默认值为 1.0，这意味着不会对遥测数据进行任何采样。
`OTEL_PYTHON_DISABLED_INSTRUMENTATIONS`	指定要禁用的 OpenTelemetry 检测。禁用后，检测不会作为自动检测的一部分执行。接受以逗号分隔的小写库名称列表。例如，将其设置为 `"psycopg2,fastapi"` 以禁用 Psycopg2 和 FastAPI 检测。它默认为空列表，启用所有支持的检测。

添加社区检测库

从 OpenTelemetry 社区包含检测库时，可以自动收集更多数据。

注意

我们不支持也不保证社区检测库的质量。要为我们的分发版推荐一个检测库，请在反馈社区中发帖或投票。请注意，某些检测库基于实验性 OpenTelemetry 规范，可能会在将来引入中断性变更。

若要添加社区 OpenTelemetry Instrumentation 库，请通过应用的 requirements.txt 文件安装它。 OpenTelemetry 自动检测会自动选取并检测所有已安装的库。在此处查看社区库列表。

自动监视

若要为 Application Insights 启用遥测数据收集，只需设置以下应用程序设置：

应用程序设置定义

应用设置名称	定义	值
APPLICATIONINSIGHTS_CONNECTION_STRING	Application Insights 资源的连接字符串	示例：abcd1234-ab12-cd34-abcd1234abcd
ApplicationInsightsAgent_EXTENSION_VERSION	用于控制运行时监视的主扩展。	`~3`

注意

Profiler 和快照调试器不适用于 Python 应用程序

使用 Azure 资源管理器配置应用服务应用程序设置

可以使用 Azure 资源管理器模板来管理和配置 Azure 应用服务的应用程序设置。在使用资源管理器自动化部署新的应用服务资源或修改现有资源的设置时，可以使用此方法。

下面是应用服务资源的应用程序设置 JSON 的基本结构：

      "resources": [
        {
          "name": "appsettings",
          "type": "config",
          "apiVersion": "2015-08-01",
          "dependsOn": [
            "[resourceId('Microsoft.Web/sites', variables('webSiteName'))]"
          ],
          "tags": {
            "displayName": "Application Insights Settings"
          },
          "properties": {
            "key1": "value1",
            "key2": "value2"
          }
        }
      ]

若要了解为 Application Insights 配置了应用程序设置的资源管理器模板的示例，可参阅此模板。具体请参阅从第 238 行开始的部分。

自动创建 Application Insights 资源并链接到新建的应用服务资源

若要创建使用默认 Application Insights 设置的资源管理器模板，请像创建启用了 Application Insights 的新 Web 应用程序一样开始该过程。

使用所需的 Web 应用信息创建新的应用服务资源。在“监视”选项卡上启用 Application Insights。
选择“查看 + 创建”。然后，选择“下载自动化模板”。

此选项将生成配置了全部所需设置的最新资源管理器模板。

在以下示例中，将 AppMonitoredSite 的所有实例替换为你的站点名称：

注意

如果使用 Windows，请将 ApplicationInsightsAgent_EXTENSION_VERSION 设置为 ~2。如果使用 Linux，请将 ApplicationInsightsAgent_EXTENSION_VERSION 设置为 ~3。

{
    "resources": [
        {
            "name": "[parameters('name')]",
            "type": "Microsoft.Web/sites",
            "properties": {
                "siteConfig": {
                    "appSettings": [
                        {
                            "name": "APPINSIGHTS_INSTRUMENTATIONKEY",
                            "value": "[reference('microsoft.insights/components/AppMonitoredSite', '2015-05-01').InstrumentationKey]"
                        },
                        {
                            "name": "APPLICATIONINSIGHTS_CONNECTION_STRING",
                            "value": "[reference('microsoft.insights/components/AppMonitoredSite', '2015-05-01').ConnectionString]"
                        },
                        {
                            "name": "ApplicationInsightsAgent_EXTENSION_VERSION",
                            "value": "~2"
                        }
                    ]
                },
                "name": "[parameters('name')]",
                "serverFarmId": "[concat('/subscriptions/', parameters('subscriptionId'),'/resourcegroups/', parameters('serverFarmResourceGroup'), '/providers/Microsoft.Web/serverfarms/', parameters('hostingPlanName'))]",
                "hostingEnvironment": "[parameters('hostingEnvironment')]"
            },
            "dependsOn": [
                "[concat('Microsoft.Web/serverfarms/', parameters('hostingPlanName'))]",
                "microsoft.insights/components/AppMonitoredSite"
            ],
            "apiVersion": "2016-03-01",
            "location": "[parameters('location')]"
        },
        {
            "apiVersion": "2016-09-01",
            "name": "[parameters('hostingPlanName')]",
            "type": "Microsoft.Web/serverfarms",
            "location": "[parameters('location')]",
            "properties": {
                "name": "[parameters('hostingPlanName')]",
                "workerSizeId": "[parameters('workerSize')]",
                "numberOfWorkers": "1",
                "hostingEnvironment": "[parameters('hostingEnvironment')]"
            },
            "sku": {
                "Tier": "[parameters('sku')]",
                "Name": "[parameters('skuCode')]"
            }
        },
        {
            "apiVersion": "2015-05-01",
            "name": "AppMonitoredSite",
            "type": "microsoft.insights/components",
            "location": "China North 2",
            "properties": {
                "ApplicationId": "[parameters('name')]",
                "Request_Source": "IbizaWebAppExtensionCreate"
            }
        }
    ],
    "parameters": {
        "name": {
            "type": "string"
        },
        "hostingPlanName": {
            "type": "string"
        },
        "hostingEnvironment": {
            "type": "string"
        },
        "location": {
            "type": "string"
        },
        "sku": {
            "type": "string"
        },
        "skuCode": {
            "type": "string"
        },
        "workerSize": {
            "type": "string"
        },
        "serverFarmResourceGroup": {
            "type": "string"
        },
        "subscriptionId": {
            "type": "string"
        }
    },
    "$schema": "https://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0"
}

通过 PowerShell 启用

若要通过 PowerShell 启用应用程序监视，仅须更改基础的应用程序设置。以下示例为资源组 AppMonitoredRG 中名为 AppMonitoredSite 的网站启用应用程序监视。它配置要发送到 012345678-abcd-ef01-2345-6789abcd 检测密钥的数据。

注意

建议使用 Azure Az PowerShell 模块与 Azure 交互。若要开始，请参阅安装 Azure PowerShell。若要了解如何迁移到 Az PowerShell 模块，请参阅将 Azure PowerShell 从 AzureRM 迁移到 Az。

注意

如果使用 Windows，请将 ApplicationInsightsAgent_EXTENSION_VERSION 设置为 ~2。如果使用 Linux，请将 ApplicationInsightsAgent_EXTENSION_VERSION 设置为 ~3。

$app = Get-AzWebApp -ResourceGroupName "AppMonitoredRG" -Name "AppMonitoredSite" -ErrorAction Stop
$newAppSettings = @{} # case-insensitive hash map
$app.SiteConfig.AppSettings | %{$newAppSettings[$_.Name] = $_.Value} # preserve non Application Insights application settings.
$newAppSettings["APPINSIGHTS_INSTRUMENTATIONKEY"] = "012345678-abcd-ef01-2345-6789abcd"; # set the Application Insights instrumentation key
$newAppSettings["APPLICATIONINSIGHTS_CONNECTION_STRING"] = "InstrumentationKey=012345678-abcd-ef01-2345-6789abcd"; # set the Application Insights connection string
$newAppSettings["ApplicationInsightsAgent_EXTENSION_VERSION"] = "~2"; # enable the ApplicationInsightsAgent
$app = Set-AzWebApp -AppSettings $newAppSettings -ResourceGroupName $app.ResourceGroup -Name $app.Name -ErrorAction Stop

Django Instrumentation

若要使用 OpenTelemetry Django Instrumentation，需要在应用服务设置中将 DJANGO_SETTINGS_MODULE 环境变量设置为从应用文件夹指向设置模块。有关详细信息，请参阅 Django 文档。

常见问题解答

Application Insights 中的标准指标与 Azure 应用服务指标之间有何区别？

Application Insights 为向应用程序发出的请求收集遥测数据。如果在 WebApps/WebServer 中发生故障，并且请求未到达用户应用程序，则 Application Insights 不会有任何有关它的遥测数据。

Application Insights 算出的 serverresponsetime 持续时间不一定与 Web 应用观察到的服务器响应时间匹配。此行为是因为 Application Insights 仅计算实际到达用户应用程序的持续时间。如果请求在 WebServer 中停滞或排队，则该等待时间将包含在 Web 应用指标中，但不会包含在 Application Insights 指标中。

故障排除

在这里，我们提供了有关使用自动检测功能监视 Azure 应用服务上的 Python 应用程序的故障排除指南。

重复遥测

如果不在代码中使用 OpenTelemetry 的手动检测（例如 Azure Monitor OpenTelemetry 发行版或 Azure Monitor OpenTelemetry 导出器），则应仅在应用服务上使用自动结构。在手动检测的基础上使用自动检测可能会导致重复遥测并增加成本。若要使用应用服务 OpenTelemetry 自动检测，请先从代码中移除 OpenTelemetry 的手动检测。

缺少遥测

如果缺少遥测数据，请按照以下步骤确认已正确启用自动检测。

步骤 1：检查应用服务资源上的 Application Insights 边栏选项卡

确认在应用服务资源上的 Application Insights 边栏选项卡中启用了自动检测：

步骤 2：确认应用设置正确

确认 ApplicationInsightsAgent_EXTENSION_VERSION 应用设置已设置为 ~3 值，并且 APPLICATIONINSIGHTS_CONNECTION_STRING 指向相应的 Application Insights 资源。

步骤 3：检查自动检测诊断和状态日志

导航到 /var/log/applicationinsights/ 并打开 status_*.json。

确认 AgentInitializedSuccessfully 设置为“true”，且 IKey 为有效的 iKey。

下面是示例 JSON 文件：

    "AgentInitializedSuccessfully":true,
            
    "AppType":"python",
            
    "MachineName":"c89d3a6d0357",
            
    "PID":"47",
            
    "IKey":"00000000-0000-0000-0000-000000000000",
            
    "SdkVersion":"1.0.0"

同一文件夹中的 applicationinsights-extension.log 文件可能会显示其他有用的诊断。

Django 应用

如果应用使用 Django 并且无法启动或使用不正确的设置，请确保设置 DJANGO_SETTINGS_MODULE 环境变量。有关详细信息，请参阅 Django Instrumentation 部分。

测试应用程序主机与引入服务之间的连接性

Application Insights SDK 和代理发送遥测，将其作为 REST 调用引入到引入终结点。可以使用原始 REST 客户端通过 PowerShell 或使用 curl 命令，测试从 Web 服务器或应用程序主机计算机到引入服务终结点的连接。请参阅排查 Azure Monitor Application Insights 中缺失应用程序遥测的问题。

有关最新的更新和 bug 修复，请参阅发行说明。 -->

后续步骤

将 Azure 诊断配置为向 Application Insights 发送数据
监视服务运行状况指标以确保服务可用且做出快速响应
每当操作事件发生或指标超过阈值时接收警报通知
可用性概述

通过