Python 应用接入 Azure Application Insights：基于 OpenTelemetry 的完整插桩指南

Python 应用接入 Azure Application Insights：基于 OpenTelemetry 的完整插桩指南

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot

导读

本文基于 awesome-copilot 仓库中appinsights-instrumentationskill 的 PYTHON 参考指南，系统讲解如何为部署在 Azure 上的 Python Web 应用接入 Azure Application Insights（App Insights），实现日志、指标与分布式追踪的可观测性。读完本文，你将掌握三个核心能力：安装并配置azure-monitor-opentelemetry客户端库、为应用注入APPLICATIONINSIGHTS_CONNECTION_STRING环境变量（含 Azure CLI 与 IaC 两种方式）、以及通过标准库logging体系发送自定义遥测事件。

一、技能全景：appinsights-instrumentation 是什么

在 SKILL.md 中，该 skill 的定位是："Instrument a webapp to send useful telemetry data to Azure App Insights"——将 Web 应用的遥测数据发送到 Azure App Insights，以提升对应用健康状态的可观测性。其使用时机非常明确：当用户希望为自己的 Web 应用启用遥测能力时。

该 skill 覆盖三类语言栈，并各自维护一份参考指南：

• ASP.NET Core 应用：见 ASPNETCORE.md，使用Azure.Monitor.OpenTelemetry.AspNetCore包；
• Node.js 应用：见 NODEJS.md，使用@azure/monitor-opentelemetry包；
• Python 应用：即本文主体，使用azure-monitor-opentelemetry包。

此外，AUTO.md 还描述了无需改代码的自动插桩（codeless instrumentation）方案，但仅支持托管在 Azure App Service 中的 ASP.NET Core 与 Node.js 应用，Python 应用不在其列，因此 Python 场景一律采用本文所述的手动插桩路径。

插桩前的工作流

根据 SKILL.md 的 Guidelines，动手改代码之前需要完成两项准备：

1. 收集上下文信息：确定应用的（编程语言、应用框架、托管方式）三元组。Python 应用需要进一步明确其托管形态——个人电脑本地、Azure App Service（代码）、Azure App Service（容器）还是 Azure Container App 等，托管形态直接决定后续环境变量的注入方式。
2. 创建 App Insights 资源：在 examples/appinsights.bicep（Bicep IaC 方式）与 scripts/appinsights.ps1（Azure CLI 方式）之间二选一。

二、第一步：创建 Application Insights 资源

无论选择哪种方式，skill 都建议将 App Insights 资源创建在"有意义"的资源组中——最佳候选是托管应用所在的同一个资源组，便于资源统一管理。

方式 A：通过 Bicep IaC 模板

如果你的工作区中已有 Bicep 模板文件，这是首选方案。完整可参考 examples/appinsights.bicep，核心片段如下：

@description('Location for all resources') param location string = resourceGroup().location @description('Name for new Application Insights') param name string // Create Log Analytics Workspace resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2022-10-01' = { name: '${name}-workspace' location: location properties: { sku: { name: 'PerGB2018' } retentionInDays: 30 } } // Create Application Insights resource applicationInsights 'Microsoft.Insights/components@2020-02-02' = { name: name location: location kind: 'web' properties: { Application_Type: 'web' WorkspaceResourceId: logAnalyticsWorkspace.id } } output connectionString string = applicationInsights.properties.ConnectionString

该模板体现了一个重要的现代实践：基于工作区（workspace-based）的 App Insights 架构。App Insights 不再自带独立存储，而是把遥测数据落入一个 Log Analytics Workspace（SKU 为PerGB2018、默认保留 30 天），两者通过WorkspaceResourceId关联。模板最后通过output connectionString直接导出连接字符串，部署后可直接取用，省去手工查询。

方式 B：通过 Azure CLI

若项目没有 IaC 模板，可参考 scripts/appinsights.ps1 中的三步命令：

# 1. 添加 Application Insights 扩展 az extension add -n application-insights # 2. 创建 Log Analytics 工作区 az monitor log-analytics workspace create --resource-group $resourceGroupName --workspace-name $logAnalyticsWorkspaceName --location $azureRegionName # 3. 创建 Application Insights 资源（关联工作区） az monitor app-insights component create --app $applicationInsightsResourceName --location $azureRegionName --resource-group $resourceGroupName --workspace $logAnalyticsWorkspaceName

注意脚本中的$resourceGroupName、$logAnalyticsWorkspaceName、$azureRegionName、$applicationInsightsResourceName均为占位变量，执行前需自行赋值。此流程与 Bicep 模板在架构上完全一致：先建 Log Analytics 工作区，再创建与该工作区关联的 App Insights 组件。

三、第二步：安装客户端库

在 Python 应用中接入 Azure Monitor，官方推荐的客户端库是 OpenTelemetry 发行包：

pip install azure-monitor-opentelemetry

该包基于 OpenTelemetry 生态封装了 Azure Monitor 导出器，安装后应用即可通过 OpenTelemetry 的 tracing/metrics/logging 管线把遥测数据导出到 App Insights。它是 PYTHON.md 中整个插桩流程的依赖基础。

四、第三步：配置应用以使用 Azure Monitor

PYTHON.md 指出：Python 应用通过 Python 标准库中的logging体系发送遥测。因此，插桩的关键是创建一个模块，在其中完成 Azure Monitor 的初始化，并产出一个"可发送遥测的 logger"。

建议将配置逻辑独立成模块（例如telemetry.py），代码如下：

import logging from azure.monitor.opentelemetry import configure_azure_monitor configure_azure_monitor( logger_name="<your_logger_namespace>" ) logger = logging.getLogger("<your_logger_namespace>")

要点说明：

• configure_azure_monitor()是包提供的核心初始化入口，它负责配置 OpenTelemetry 并启动遥测导出。调用时通过logger_name参数指定日志命名空间，该命名空间与后续logging.getLogger()传入的名字必须一致，两者构成"配对"关系。
• logger_name建议使用应用的模块命名空间（如myapp.service），便于在 App Insights 中按命名空间过滤日志。
• 一个易被忽略的前提：代码修改后必须重新部署应用才能生效（原文档明确标注了该注意事项）。本地开发环境下修改只影响本地运行实例。

五、第四步：配置 App Insights 连接字符串

App Insights 资源带有一个连接字符串（connection string），它包含遥测的接入端点与资源标识信息。需要将其以环境变量APPLICATIONINSIGHTS_CONNECTION_STRING的形式注入运行中的应用。

5.1 查询连接字符串

使用 Azure CLI 查询（命令出处：scripts/appinsights.ps1）：

az monitor app-insights component show --app $applicationInsightsResourceName --resource-group $resourceGroupName --query connectionString --output tsv

若使用前文的 Bicep 模板部署，output connectionString会直接给出该值，可免去此查询。

5.2 注入环境变量

拿到连接字符串后，将其值赋给环境变量：

APPLICATIONINSIGHTS_CONNECTION_STRING={your_application_insights_connection_string}

值得强调的是，PYTHON.md 及其姊妹指南 ASPNETCORE.md 均将环境变量视为新推荐方式，并特别警告不要沿用旧式做法（如 ASP.NET Core 场景中禁止修改appsettings.json来配置）。Python 应用同理：环境变量是标准且跨部署形态通用的注入手段。

5.3 注入方式由托管形态决定

• 应用使用 IaC 模板（Bicep/Terraform）表示云上资源时：应把该环境变量直接写进 IaC 模板，使其在每次部署时自动应用，避免手工重复配置。
• 没有 IaC 模板时：使用 Azure CLI 手工为云上应用实例设置环境变量，scripts/appinsights.ps1 提供了三种常见托管形态的命令：

# Azure App Service（Web 应用） az webapp config appsettings set --resource-group $resourceGroupName --name $appName --settings $key=$value # Azure Container App（新建或更新已有容器应用） az containerapp update -n $containerAppName -g $resourceGroupName --set-env-vars $key=$value # Azure Function App（函数应用） az functionapp config appsettings set --name $functionName --resource-group $ResourceGroupName --settings $key=$value

其中$key即APPLICATIONINSIGHTS_CONNECTION_STRING，$value为查询到的连接字符串。对照 SKILL.md 中"必须询问用户应用托管位置"的要求，此处正是托管形态决定具体命令的落点。

六、第五步：发送遥测数据

完成初始化与连接字符串注入后，即可开始发送遥测。首先创建并配置 logger：

logger = logging.getLogger("<your_logger_namespace>") logger.setLevel(logging.INFO)

setLevel(logging.INFO)设定日志级别门槛，INFO及以上级别（INFO/WARNING/ERROR/CRITICAL）的日志会被处理，DEBUG级别默认被过滤。之后即可像使用普通 logger 一样发送事件：

logger.info("info log")

由于 Azure Monitor 的 Python 客户端会通过 logging handler 将日志接入 OpenTelemetry 管线，因此logger.info("info log")发出的每条日志都会作为遥测记录进入 App Insights 的traces表。你可以在应用中任意位置导入并复用这一 logger，形成统一的日志命名空间管理。

七、从源码结构看整个插桩链路

结合本 skill 的完整文件布局，可以梳理出一条清晰的端到端链路：

从文件命名与结构可以推断，该 skill 对"资源创建—代码修改—环境配置—数据发送"四个环节做了刻意分离，保证同一条插桩方法论可在 ASP.NET Core、Node.js、Python 三种语言栈间复用，仅"代码修改"环节因语言而异（分别落在 ASPNETCORE.md、NODEJS.md 与 PYTHON.md）。该 skill 由微软以 MIT 协议开源（见 LICENSE.txt），属于 GitHub Copilot Agents 生态中 appinsights-instrumentation 技能包的组成部分。

八、最佳实践清单

综合 PYTHON.md 与其配套文件，落地 Python 插桩时建议遵循以下实践：

1. 优先工作区架构：App Insights 一律关联 Log Analytics 工作区（Bicep 模板与 CLI 脚本均体现此模式），以便统一查询与成本治理。
2. 资源就近放置：将 App Insights 创建在应用所在资源组，便于管理与权限收敛。
3. 环境变量唯一来源：连接字符串只经APPLICATIONINSIGHTS_CONNECTION_STRING环境变量注入，不写死进代码或旧式配置文件。
4. IaC 优先：存在 Bicep/Terraform 模板时，把环境变量写入模板，保证"部署即生效"。
5. 命名空间统一：configure_azure_monitor(logger_name=...)与logging.getLogger(...)使用相同命名空间，避免遥测丢失或日志归属混乱。
6. 改动必部署：代码插桩完成后必须重新部署应用，本地修改不会自动同步到云端运行实例。
7. 按需调整日志级别：生产环境建议保持INFO级别基线，排查问题时可临时下调级别以观察DEBUG日志。

结语

借助azure-monitor-opentelemetry与标准库logging，Python 应用仅需一个模块、一段初始化代码和一个环境变量，即可将应用日志接入 Azure Application Insights。本文所述每一步均可对照 references/PYTHON.md、SKILL.md、examples/appinsights.bicep 与 scripts/appinsights.ps1 在仓库中逐一验证，是面向 Python Web 应用的完整、可复现的观测性接入方案。

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot