Agentic Awesome Skills 中的 Azure Monitor OpenTelemetry Python 可观测性 Skill 实战指南

AI 技能AI 插件【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址https://gitcode.com/gh_mirrors/an/agentic-awesome-skills点击查看免费下载本指南以 plugins/agentic-awesome-skills-claude/skills/azure-monitor-opentelemetry-py/SKILL.md 为核心主体系统讲解如何基于azure-monitor-opentelemetry发行版Distro以一行代码完成 Application Insights 接入与 OpenTelemetry 自动埋点。读完本文你将掌握连接字符串配置、三大主流 Web 框架Flask / Django / FastAPI的零侵入接入、自定义 Trace / Metrics / Logs、采样与云角色名设置、AAD 认证等完整实战能力并能理解该 Skill 在 AAS 仓库中云可观测性分类下的定位与适用边界。一、Skill 定位为什么需要一行式接入在现代 Python 应用中可观测性通常包含三条数据链路分布式追踪Traces、指标Metrics与日志Logs。手工接入这三者需要分别配置 SDK、导出器Exporter与仪表化库Instrumentation Library步骤繁琐且极易出错。Azure Monitor OpenTelemetry Distroazure-monitor-opentelemetry通过一个统一的入口函数configure_azure_monitor()把上述过程封装为一次调用它负责读取连接字符串、初始化 OpenTelemetry SDK 的 Trace / Metrics / Logs 三个信号管道、装配 Azure Monitor 导出器并自动启用常见第三方库的仪表化。这正是本 Skill 的核心价值——以最小的代码改动为 Python 应用建立通往 Application Insights 的可观测性管道。在 skills/azure-monitor-opentelemetry-py/SKILL.md以及 Claude 插件侧的同名文件中该 Skill 的元数据明确标注为risk: critical、source: community、分类cloud并在 data/skills_index.json 的索引条目id: azure-monitor-opentelemetry-py中登记同时支持codex与claude两种 Agent 目标。也就是说在 AAS 的 Skill 生态中它属于云平台可观测性类别、风险等级为关键的社区技能——Agent 在识别到为 Python 服务接入 Application Insights / Azure Monitor 可观测性这类任务时会被自动匹配。二、安装与连接字符串配置2.1 安装pip install azure-monitor-opentelemetry该包是接入的核心依赖它同时会带入 OpenTelemetry SDK 与 Azure Monitor Exporter 的相关组件。若你的项目使用requirements.txt或pyproject.toml管理依赖请将该包加入其中以确保部署环境一致。2.2 环境变量推荐用于生产APPLICATIONINSIGHTS_CONNECTION_STRINGInstrumentationKeyxxx;IngestionEndpointhttps://xxx.in.applicationinsights.azure.com/连接字符串Connection String是 Application Insights 资源的访问凭证由InstrumentationKey仪表密钥与IngestionEndpoint数据摄取端点两部分组成。将其放入环境变量后configure_azure_monitor()在未显式传参时会自动读取从而避免把敏感信息硬编码进源码。提示实际部署时请将xxx替换为你在 Azure 门户中 Application Insights 资源里真实获取的连接字符串在不同 Azure 区域中IngestionEndpoint的主机名如.in.applicationinsights.azure.com前缀可能不同以门户提供的值为准。三、快速开始与显式配置3.1 快速开始读取环境变量from azure.monitor.opentelemetry import configure_azure_monitor # One-line setup - reads connection string from environment configure_azure_monitor() # Your application code...这是最简接入方式不传任何参数仅依赖APPLICATIONINSIGHTS_CONNECTION_STRING环境变量完成初始化。3.2 显式配置代码内传入连接字符串from azure.monitor.opentelemetry import configure_azure_monitor configure_azure_monitor( connection_stringInstrumentationKeyxxx;IngestionEndpointhttps://xxx.in.applicationinsights.azure.com/ )适合本地开发、临时环境或无法使用环境变量的场景。两种方式等价实际生产建议优先采用环境变量方案见文末最佳实践。四、主流 Web 框架接入Distro 的核心优势在于对常见框架的自动仪表化只需在框架对象创建之前调用configure_azure_monitor()随后创建的 Flask、Django、FastAPI 应用便会自动产生分布式追踪数据。4.1 Flaskfrom flask import Flask from azure.monitor.opentelemetry import configure_azure_monitor configure_azure_monitor() app Flask(__name__) app.route(/) def hello(): return Hello, World! if __name__ __main__: app.run()4.2 Django# settings.py from azure.monitor.opentelemetry import configure_azure_monitor configure_azure_monitor() # Django settings...Django 场景下初始化应放在settings.py中且位于任意视图/中间件加载之前从而保证请求链路从一开始就被正确捕获。4.3 FastAPIfrom fastapi import FastAPI from azure.monitor.opentelemetry import configure_azure_monitor configure_azure_monitor() app FastAPI() app.get(/) async def root(): return {message: Hello World}三个框架的使用模式完全一致——先初始化 Distro再定义应用对象。这一点对异步框架FastAPI、aiohttp同样成立Distro 会一并处理其异步上下文传播。五、自定义 TelemetryTrace、Metrics、Logs除了自动采集你还可以通过标准的 OpenTelemetry API 在业务代码中注入自定义数据用于更精细的链路追踪、业务指标与日志关联。5.1 自定义 Tracesfrom opentelemetry import trace from azure.monitor.opentelemetry import configure_azure_monitor configure_azure_monitor() tracer trace.get_tracer(__name__) with tracer.start_as_current_span(my-operation) as span: span.set_attribute(custom.attribute, value) # Do work...要点通过trace.get_tracer(__name__)获取 Tracerstart_as_current_span将新 Span 挂到当前上下文span.set_attribute()可写入自定义属性如业务订单号、用户 ID这些属性后续可用于 Application Insights 中的查询与筛选。5.2 自定义 Metricsfrom opentelemetry import metrics from azure.monitor.opentelemetry import configure_azure_monitor configure_azure_monitor() meter metrics.get_meter(__name__) counter meter.create_counter(my_counter) counter.add(1, {dimension: value})OpenTelemetry 指标 API 支持 Counter、Histogram、ObservableCounter 等类型上例以 Counter 为例每次counter.add()都会累加计数并可通过 attributes维度做细分统计最终呈现在 Application Insights 的指标/自定义指标视图中。5.3 自定义 Logsimport logging from azure.monitor.opentelemetry import configure_azure_monitor configure_azure_monitor() logger logging.getLogger(__name__) logger.setLevel(logging.INFO) logger.info(This will appear in Application Insights) logger.error(Errors are captured too, exc_infoTrue)调用configure_azure_monitor()后标准库logging的日志会自动路由到 Application InsightsDistro 会安装对应的日志处理器。建议为 logger 显式设置setLevel(logging.INFO)否则可能因默认级别过滤而丢失 INFO 级日志错误日志带上exc_infoTrue以输出堆栈信息便于后续排障。六、关键配置项深入采样、云角色名与仪表化控制6.1 采样Sampling高流量场景下为控制成本与摄取量可以按比例采样from azure.monitor.opentelemetry import configure_azure_monitor # Sample 10% of requests configure_azure_monitor( sampling_ratio0.1 )sampling_ratio取值范围为0.0 ~ 1.0默认1.0全量。0.1即仅采集 10% 的请求追踪。6.2 云角色名Cloud Role Name在微服务/多服务架构中为每个服务设置唯一的云角色名可以让 Application Map应用拓扑图正确区分各个组件from azure.monitor.opentelemetry import configure_azure_monitor from opentelemetry.sdk.resources import Resource, SERVICE_NAME configure_azure_monitor( resourceResource.create({SERVICE_NAME: my-service-name}) )原理OpenTelemetry 的Resource携带服务标识元数据Distro 会把其中的SERVICE_NAME映射为 Application Insights 的 cloud_RoleName 字段从而在应用地图上以my-service-name标识该节点。6.3 精确控制启用哪些仪表化默认启用全部支持的仪表化库若只想启用部分库可显式传入instrumentations列表from azure.monitor.opentelemetry import configure_azure_monitor configure_azure_monitor( instrumentations[flask, requests] # Only enable these )这既可用于减少不必要的埋点开销也可避免某些库的自动仪表化与业务逻辑冲突。若未传入该参数则默认启用下表中的全部仪表化。6.4 Live Metrics 实时指标流from azure.monitor.opentelemetry import configure_azure_monitor configure_azure_monitor( enable_live_metricsTrue )enable_live_metrics默认False设为True后可在 Azure 门户的实时指标Live Metrics视图中近乎实时地观察请求量、性能与异常适合发布上线或压测期间进行即时监控。6.5 Azure AD 认证无需将连接字符串写入配置改用 Azure AD 托管身份/服务主体认证from azure.monitor.opentelemetry import configure_azure_monitor from azure.identity import DefaultAzureCredential configure_azure_monitor( credentialDefaultAzureCredential() )DefaultAzureCredential会按顺序尝试环境变量、托管身份、Azure CLI 等多种凭据来源适合在 AKS、VM 等支持托管身份的生产环境使用避免密钥管理风险。七、自动仪表化清单与配置参数总览7.1 内置自动仪表化库LibraryTelemetry TypeFlaskTracesDjangoTracesFastAPITracesRequestsTracesurllib3TraceshttpxTracesaiohttpTracespsycopg2TracespymysqlTracespymongoTracesredisTraces覆盖了 Web 框架、HTTP 客户端同步与异步以及主流数据库驱动PostgreSQL、MySQL、MongoDB、Redis意味着大多数典型后端服务的入口调用与下游数据访问都会被自动纳入追踪。7.2configure_azure_monitor()配置参数总览ParameterDescriptionDefaultconnection_stringApplication Insights connection stringFrom env varcredentialAzure credential for AAD authNonesampling_ratioSampling rate (0.0 to 1.0)1.0resourceOpenTelemetry ResourceAuto-detectedinstrumentationsList of instrumentations to enableAllenable_live_metricsEnable Live Metrics streamFalse八、最佳实践综合 Skill 文档与工程经验建议在接入时遵循以下规范尽早调用configure_azure_monitor()—— 必须在导入/实例化被仪表化的库如 Flask、requests之前完成初始化确保仪表化钩子能够挂载生效生产环境使用环境变量承载连接字符串避免密钥泄漏同时便于在部署平台如 App Service、AKS上按环境注入多服务应用务必设置云角色名Cloud Role Name保证 Application Map 拓扑清晰可辨高流量应用开启采样通过sampling_ratio控制成本与数据量使用结构化日志便于在 Log Analytics 中执行高效的 KQL 查询与关联分析为 Span 添加自定义属性记录业务关键字段提升问题定位与排查效率生产负载优先采用 AAD 认证credential参数替代静态连接字符串的长期凭证。九、适用场景与限制何时使用本 Skill当任务明确属于为 Python 应用接入 Azure Monitor / Application Insights 可观测性需要快速完成 OpenTelemetry 自动埋点、框架接入或自定义 Trace/Metrics/Logs 上报时本 Skill 提供了一站式、可直接落地的执行路径。使用限制仅当任务范围与上述描述清晰匹配时才使用本 Skill避免在无关场景下强行套用输出结果不能替代针对具体环境的验证、测试或专家评审——接入后请务必在真实环境中确认数据确实到达 Application Insights若缺少必要的输入如连接字符串、权限边界、成功标准应停下来向用户确认而不是擅自假设。十、在 AAS 仓库中的延伸阅读本 Skill 的 Claude 插件版本plugins/agentic-awesome-skills-claude/skills/azure-monitor-opentelemetry-py/SKILL.md本 Skill 的核心库版本skills/azure-monitor-opentelemetry-py/SKILL.mdSkill 索引登记分类cloud、风险criticaldata/skills_index.json仓库中还提供了 TypeScript 与 Java 版本的同源 Skillazure-monitor-opentelemetry-ts、azure-monitor-opentelemetry-exporter-java若你的技术栈涉及多语言可对照查看。通过本 SkillAgent 可以在一分钟内为 Python 服务建立完整的 Application Insights 可观测性管道配合采样、云角色名、AAD 认证等高级配置即可平滑适配从单体应用到微服务集群的各类生产场景。赞分享AI 技能AI 插件【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址https://gitcode.com/gh_mirrors/an/agentic-awesome-skills点击查看免费下载相关推荐agentic-awesome-skills 实战Azure Monitor OpenTelemetry Exporter for Python 低层遥测导出指南agentic awesome skills 实战Azure Monitor OpenTelemetry Exporter for Python 低层遥测导出AI 技能AI 插件agentic-awesome-skills 实战Java 应用接入 Azure Monitor OpenTelemetry Exporter 与 Autoconfigure 迁移指南agentic awesome skills 实战Java 应用接入 Azure Monitor OpenTelemetry Exporter 与 AutocAI 技能AI 插件Agentic Awesome Skills 实战使用 azure-monitor-ingestion-java 将自定义日志写入 Azure MonitorAgentic Awesome Skills 实战使用 azure monitor ingestion java 将自定义日志写入 Azure MonitorAI 技能AI 插件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考