Azure App 服務 和 Python 的應用程式監視 （預覽）

  • 發行項

重要

請參閱 Microsoft Azure 預覽版增補使用規定，以了解適用於 Azure 功能 (搶鮮版 (Beta)、預覽版，或尚未正式發行的版本) 的法律條款。

在 Azure App 服務 上監視 Python Web 應用程式，而不需修改程式碼。 本指南說明如何啟用 Azure 監視器 Application Insights，並提供自動化大規模部署的秘訣。

整合工具程式代碼中常用的 Python 連結庫，可讓您自動收集並相互關聯相依性、記錄和計量。 檢測之後，您會從下列 Python 連結庫收集呼叫和計量：

測試設備 支援的連結庫名稱 支援的版本
OpenTelemetry Django Instrumentation django 連結
OpenTelemetry FastApi Instrumentation fastapi 連結
OpenTelemetry Flask Instrumentation flask 連結
OpenTelemetry Psycopg2 Instrumentation psycopg2 連結
OpenTelemetry 要求檢測 requests 連結
OpenTelemetry UrlLib Instrumentation urllib 全部
OpenTelemetry UrlLib3 Instrumentation urllib3 連結

注意

如果使用 Django，請參閱 本文中的其他 Django Instrumentation 一節。

記錄遙測會收集在根記錄器層級。 若要深入瞭解 Python 的原生記錄階層，請流覽 Python 記錄檔。

必要條件

  • Python 3.11 版或更新版本。
  • App Service 必須部署為程序代碼。 不支援自定義容器。

啟用 Application Insights

在 Azure App 服務 上監視 Python 應用程式最簡單的方式是透過 Azure 入口網站。

啟用 Azure 入口網站 中的監視會自動使用 Application Insights 來檢測您的應用程式，而且不需要變更程式代碼。

注意

如果您未在程式代碼中使用 OpenTelemetry 的手動檢測，例如 Azure 監視器 OpenTelemetry Distro 或 Azure 監視器 OpenTelemetry 導出工具，則應該只在 App Service 上使用自動結構。 這是為了避免傳送重複的數據。 若要深入瞭解這一點，請參閱 本文中的疑難解答一節 。

透過 Azure 入口網站 自動結構

如需支援自動結構案例的完整清單，請參閱 支援的環境、語言和資源提供者。

在 Azure App 服務 中切換 Python 應用程式的監視，不需要變更程式碼。

適用於 Python 的 Application Insights 與程式代碼型 Linux Azure App 服務 整合。

整合處於公開預覽狀態。 它會新增在 GA 中的 Python SDK。

  1. 在 App Service 的 Azure 控制面板中選取 [Application Insights ]，然後選取 [ 啟用]。

    [Application Insights] 索引卷標的螢幕快照，其中已選取 [啟用]。

  2. 選擇建立新的資源，或為此應用程式選取現有的 Application Insights 資源。

    注意

    當您選取 [ 確定 ] 以建立新的資源時，系統會提示您套 用監視設定。 選取 [ 繼續] 會將新的 Application Insights 資源連結到您的應用程式服務，這麼做也會 觸發 App Service 的重新啟動。

    [變更資源] 下拉式清單的螢幕快照。

  3. 您可以指定資源，並準備好使用。

    檢測應用程式的螢幕快照。

組態

您可以使用 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_PYTHON_DISABLED_INSTRUMENTATIONS 指定要停用的 OpenTelemetry 檢測。 停用時，不會在自動結構中執行檢測。 接受小寫 連結庫名稱的逗號分隔清單。 例如，將它設定為 "psycopg2,fastapi" 以停用 Psycopg2 和 FastAPI 檢測。 預設為空白清單，啟用所有支持的檢測。

新增社群檢測程式庫

您從 OpenTelemetry 社群包含檢測程式庫時，可以自動收集更多資料。

警告

我們不支援或保證社群檢測程式庫的品質。 若要在我們的意見反應社群中建議發行版本、張貼或附議。 請注意，有些是以實驗性 OpenTelemetry 規格為基礎，而且可能會帶來未來的重大變更。

若要新增社群 OpenTelemetry 檢測連結庫，請透過您的應用程式檔案 requirements.txt 加以安裝。 OpenTelemetry autoinstrumentation 會自動挑選並檢測所有已安裝的連結庫。 在這裡尋找社群連結庫的清單。

自動化監視

若要使用Application Insights 啟用遙測收集，只需要設定下列應用程式設定：

App Service Application 設定 的螢幕快照，其中包含可用的 Application Insights 設定。

應用程式設定定義

應用程式設定名稱 定義 值
APPLICATIONINSIGHTS_CONNECTION_STRING Application Insights 資源的 連線 字串 範例：abcd1234-ab12-cd34-abcd1234abcd
ApplicationInsightsAgent_EXTENSION_VERSION 主要延伸模組，控制運行時間監視。 ~3

注意

分析工具和快照調試程式不適用於 Python 應用程式

搭配 Azure Resource Manager 的 App Service 應用程式設定

您可以使用 Azure Resource Manager 樣本來管理和設定 Azure App 服務 的應用程式設定。 當您使用 Resource Manager 自動化部署新的 App Service 資源，或修改現有資源的設定時，可以使用此方法。

App Service 資源的應用程式設定 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"
          }
        }
      ]

如需 Resource Manager 範例，其中已針對 Application Insights 設定應用程式設定，此 範本 會很有説明。 具體來說，請參閱從第 238 行開始的 區段。

若要使用預設 Application Insights 設定建立 Resource Manager 範本，請開始程式，就像您要建立已啟用 Application Insights 的新 Web 應用程式一樣。

  1. 使用所需的 Web 應用程式資訊建立新的 App Service 資源。 在 [ 監視] 索引標籤上啟用 Application Insights。

  2. 選取 [檢閱 + 建立]。 然後選取 [ 下載自動化的範本]。

    顯示 App Service Web 應用程式建立功能表的螢幕快照。

    此選項會產生已設定所有必要設定的最新 Resource Manager 範本。

    顯示 App Service Web 應用程式範本的螢幕快照。

在下列範例中 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": "West US 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 檢測

若要使用 OpenTelemetry Django Instrumentation，您必須將 App Service 設定中的環境變數設定 DJANGO_SETTINGS_MODULE 為從您的應用程式資料夾指向您的設定模組。 如需詳細資訊，請參閱 Django 檔。

常見問題集

Application Insights 的標準計量與 Azure App 服務 計量之間的差異為何？

Application Insights 會收集對應用程式提出要求的遙測。 如果 WebApps/WebServer 中發生失敗，且要求未連線到使用者應用程式，Application Insights 就不會有任何遙測數據。

Application Insights 所計算的 serverresponsetime 持續時間不一定符合 Web Apps 觀察到的伺服器回應時間。 此行為是因為 Application Insights 只會計算要求實際到達使用者應用程式的持續時間。 如果要求在 WebServer 中停滯或排入佇列，等候時間會包含在 Web Apps 計量中，但不包含在 Application Insights 計量中。

疑難排解

在這裡，我們提供使用自動結構監視 Azure App 服務 上的 Python 應用程式的疑難解答指南。

重複的遙測

如果您未在程式代碼中使用 OpenTelemetry 的手動檢測，例如 Azure 監視器 OpenTelemetry Distro 或 Azure 監視器 OpenTelemetry 導出工具，則應該只在 App Service 上使用自動結構。 在手動檢測之上使用自動結構可能會導致重複的遙測，並增加您的成本。 若要使用 App Service OpenTelemetry autoinstrumentation，請先從程式碼中移除 OpenTelemetry 的手動檢測。

遺漏遙測

如果您遺失遙測數據，請遵循下列步驟來確認已正確啟用自動結構。

步驟 1：檢查 App Service 資源上的 Application Insights 刀鋒視窗

確認已在 App Service 資源上的 [Application Insights] 刀鋒視窗中啟用自動結構：

[Application Insights] 索引卷標的螢幕快照，其中已選取 [啟用]。

步驟 2：確認您的應用程式 設定 正確

確認 ApplicationInsightsAgent_EXTENSION_VERSION 應用程式設定已設定為的值 ~3 ，且您的 APPLICATIONINSIGHTS_CONNECTION_STRING 指向適當的 Application Insights 資源。

App Service Application 設定 的螢幕快照，其中包含可用的 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 一節。

測試應用程式主機與擷取服務之間的連線

應用程式深入剖析 SDK 和代理程式會傳送遙測，以擷取為 REST 呼叫擷取到我們擷取的端點。 您可以使用來自 PowerShell 或 curl 命令的原始 REST 用戶端，測試從 Web 伺服器或應用程式主機電腦到擷取服務端點的連線。 請參閱針對 Azure 監視器 Application Insights 中遺失的應用程式遙測進行疑難排解。

如需最新的更新和錯誤修正，請參閱版本資訊。 -->

下一步