適用於 Azure App Service 和 Python 的應用程式監視 (預覽版)

文章
07/23/2024

重要

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

在不修改程式碼的情況下監視 Azure 應用服務上的 Python Web 應用程式。本指南介紹如何啟用 Azure 監視器 Application Insights，並提供自動執行大規模部署的提示。

整合檢測設備中常用的 Python 程式碼程式庫，讓您能夠自動收集和關聯的相依性、記錄和指標。檢測后，從以下 Python 程式庫收集呼叫和指標：

檢測	支援的程式庫名稱	支援的版本
OpenTelemetry Django 檢測設備	`django`	link
OpenTelemetry FastApi 檢測設備	`fastapi`	link
OpenTelemetry Flask 檢測設備	`flask`	link
OpenTelemetry Psycopg2 檢測設備	`psycopg2`	link
OpenTelemetry Requests 檢測設備	`requests`	link
OpenTelemetry UrlLib 檢測設備	`urllib`	全部
OpenTelemetry UrlLib3 檢測設備	`urllib3`	link

注意

如果使用 Django，請參閱本文中的其他 Django 檢測設備一節。

記錄遙測資料會收集在根記錄器等級。若要了解 Python 的原生記錄階層的詳細資訊，請造訪 Python 記錄文件。

必要條件

Python 3.11 版或之前的版本。
應用程式服務必須部署為程式碼。尚不支援自訂容器。

啟用 Application Insights

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

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

注意

如果未在程式碼中使用 OpenTelemetry 的手動檢測，例如 Azure 監視器 OpenTelemetry Distro 或 Azure Monitor OpenTelemetry 匯出工具，則僅應在應用服務上使用自動檢測。這是為了避免傳送重複的資料。請參閱本文中的疑難排解一節以進一步了解。

透過 Azure 入口網站自動檢測

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

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

適用於 Python 的 Application Insights 與代碼型 Linux Azure App Service 整合。

整合處於公開預覽狀態。它會新增在 GA 中的 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 檢測程式庫]，請透過應用程式的 requirements.txt 檔案進行安裝。 OpenTelemetry 自動檢測會自動挑選並檢測所有已安裝的程式庫。在這裡尋找社群程式庫清單。

自動監視

若要使用 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 Service 的應用程式設定。當您使用 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"
          }
        }
      ]

如需已針對 Application Insights 設定應用程式設定的 Resource Manager 範本範例，此範本可能會有所幫助。具體而言，請查看第 238 行開始的區段。

自動建立 Application Insights 資源並連結到您新建立的 App Service 資源

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

使用您想要的 Web 應用程式資訊建立新的 App Service資源。在 [監視] 索引標籤上啟用 Application Insights。
選取 [檢閱 + 建立]。接著，選取 [下載自動化的範本]。

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

在下列範例中，將 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。如果使用 Linus，請將 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 Service 計量？

Application Insights 會收集對應用程式提出要求的遙測。如果 WebApps/WebServer 中發生失敗，且要求未到達使用者應用程式，則 Application Insights 不會對其進行任何遙測。

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

疑難排解

在此，我們提供使用自動檢測 Azure App Services 上的 Python 應用程式疑難排解。

重複的遙測資料

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

遺失遙測資料

如果您遺失遙測資料，請遵循下列步驟來確認已正確啟用自動檢測。

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

確認已在 App Service 資源上的 [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 檢測設備一節以取得詳細資料。

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

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

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

下一步

能夠讓 Azure 診斷傳送至 Application Insights
監視服務健康狀態計量，確保您的服務可用且回應正常
每當發生作業事件或計量超過臨界值時，接收警示通知
可用性概觀

分享方式：