AppInsights Instrumentation Guide

AppInsights Instrumentation Guide 是什么

AppInsights Instrumentation Guide 是 Web 应用接入 Azure Application Insights 的指导资料，帮助选择自动埋点或手工 OpenTelemetry，建立请求、依赖、异常、日志和自定义业务遥测，同时控制采样与敏感数据。

适用场景与选择边界

适合为 Python、TypeScript、Java 等应用补充 APM、分布式追踪与 Container Apps 可观测性，也可审查已有埋点是否缺少上下文。创建完整 Azure 架构或部署应用应使用 Azure Prepare；事故根因排查属于 Azure Diagnostics。只需本地日志且无 Azure 监控需求时，不必接入 Application Insights。

核心能力与工作机制

流程先收集框架、托管平台、现有日志和遥测需求，优先采用低侵入自动埋点；需要业务 span、属性或自定义指标时再手工接入 Azure Monitor OpenTelemetry Distro 或 Exporter。

实际工作流

确认应用语言、运行环境和 Application Insights 资源，选择自动或手工路线；配置连接字符串与 SDK，建立请求和依赖相关性，加入采样与过滤，部署到测试环境后用真实请求检查端到端 trace。

输入、输出与交付物

需要语言框架、部署平台、现有日志方案、预期指标、数据保留与隐私要求，以及目标 Application Insights 资源。输出通常是依赖配置、启动参数、初始化代码、资源连接设置和验证查询；它提供指南而非自动承诺修改所有代码，变更文件应清楚列出。

依赖、账号与权限

需要 Application Insights 资源、Azure Monitor 或 OpenTelemetry SDK，以及对应用配置和部署环境的写权限。连接字符串放在安全配置，不写进源码。

限制与安全风险

遥测可能包含用户标识、URL、查询参数和异常内容，必须做数据最小化与过滤。过高采样率增加费用，过低会丢失稀有错误；重复自动和手工埋点可能产生双份 span。只读指导不会改变资源；安装 SDK、修改启动命令、环境变量和采样配置会改变应用行为与遥测费用。生产部署前应展示文件差异和回退方法。

适合谁使用

适合后端开发者、SRE 和平台可观测性团队，特别是准备建立统一 trace 的 Web 服务。

上手与验收建议

先在测试环境对一条关键请求链做最小埋点，观察数据质量后再扩大覆盖。用一组可识别测试请求触发成功、依赖和异常路径，在 Application Insights 中核对同一 trace 的请求、依赖、状态与自定义属性，同时确认敏感字段已过滤、采样与成本符合预期。

来源、版本与许可

本条目依据 Microsoft 官方 azure-skills 仓库固定提交中的完整 AppInsights Instrumentation Guide Skill、skills.sh 市场详情和仓库 MIT 许可证整理，核验日期为 2026 年 9 月 20 日。来源未提供官方中文展示名，因此导航保留官方英文名称。

常见问题

1. AppInsights Instrumentation Guide 主要解决什么问题？

AppInsights Instrumentation Guide 是 Web 应用接入 Azure Application Insights 的指导资料，帮助选择自动埋点或手工 OpenTelemetry，建立请求、依赖、异常、日志和自定义业务遥测，同时控制采样与敏感数据。适合为 Python、TypeScript、Java 等应用补充 APM、分布式追踪与 Container Apps 可观测性，也可审查已有埋点是否缺少上下文。

2. 开始前需要准备哪些输入和上下文？

需要语言框架、部署平台、现有日志方案、预期指标、数据保留与隐私要求，以及目标 Application Insights 资源。需要 Application Insights 资源、Azure Monitor 或 OpenTelemetry SDK，以及对应用配置和部署环境的写权限。连接字符串放在安全配置，不写进源码。

3. 执行后会得到什么结果或文件？

输出通常是依赖配置、启动参数、初始化代码、资源连接设置和验证查询；它提供指南而非自动承诺修改所有代码，变更文件应清楚列出。

4. 需要哪些账号、工具和最小权限？

需要 Application Insights 资源、Azure Monitor 或 OpenTelemetry SDK，以及对应用配置和部署环境的写权限。连接字符串放在安全配置，不写进源码。遥测可能包含用户标识、URL、查询参数和异常内容，必须做数据最小化与过滤。过高采样率增加费用，过低会丢失稀有错误；重复自动和手工埋点可能产生双份 span。

5. 它会修改本地文件或云端资源吗？

只读指导不会改变资源；安装 SDK、修改启动命令、环境变量和采样配置会改变应用行为与遥测费用。生产部署前应展示文件差异和回退方法。

6. 哪些需求不应该交给这个 Skill？

创建完整 Azure 架构或部署应用应使用 Azure Prepare；事故根因排查属于 Azure Diagnostics。只需本地日志且无 Azure 监控需求时，不必接入 Application Insights。

7. 遇到失败或结果异常时怎样处理？

没有遥测时检查连接字符串、SDK 初始化顺序、出口网络和采样；trace 断链要核对上下文传播。出现双重数据时检查自动埋点与手工 provider 是否重复注册。

8. 如何验收结果确实可靠？

用一组可识别测试请求触发成功、依赖和异常路径，在 Application Insights 中核对同一 trace 的请求、依赖、状态与自定义属性，同时确认敏感字段已过滤、采样与成本符合预期。