appinsights-instrumentation

appinsights-instrumentation 技能概览

appinsights-instrumentation skill 的核心价值，是帮助代理为 Web 应用接入 Azure Application Insights 遥测，比泛泛一句“加上可观测性”更少走弯路。它真正解决的不只是“把日志打开”，而是根据应用的语言和托管方式选择合适的埋点路径，创建或接入 App Insights 资源，并确保应用拿到必需的 APPLICATIONINSIGHTS_CONNECTION_STRING。

这个技能最适合谁

如果你的 Web 应用跑在 Azure 上，希望有人能务实地帮你完成可观测性埋点，那么这个 skill 会很合适，尤其适用于：

• 托管在 Azure 上的 ASP.NET Core 应用
• 托管在 Azure 上的 Node.js 应用
• 使用 Azure App Service 的团队
• 已经在仓库中使用 Bicep 等 IaC，希望把遥测配置整洁地纳入基础设施代码的项目

当你希望代理先检查仓库、推断框架细节，再判断该走 auto-instrumentation 还是代码改造时，这个 skill 也很有用。

用户最先关心的，通常是什么

在安装 appinsights-instrumentation 之前，多数用户首先想知道这些问题的答案：

• 它适不适合我的应用技术栈？
• 我能不能不改代码？
• 具体要改哪些文件？
• App Insights 的 connection string 要怎么创建或找到？
• 我应该改基础设施代码，还是手工补设置就行？

相比笼统的“加 observability”指令，这个 skill 更直接地回应了这些落地时最常见的采用障碍。

关键差异：自动埋点还是手动埋点

appinsights-instrumentation skill 最大的价值之一，就是不会把所有应用一视同仁。它会明确优先为受支持的 Azure App Service 场景选择 auto-instrumentation，只有在需要时才退回到手动代码改造。

这点很重要，因为很多团队如果 Azure App Service 已经支持，显然更希望在不碰业务代码的前提下启用遥测。

仓库中体现出的支持路径

从仓库内容来看，实际可用的路径包括：

• 针对受支持的 ASP.NET Core 和 Node.js 应用，使用 Azure App Service auto-instrumentation
• 使用 Azure.Monitor.OpenTelemetry.AspNetCore 进行 ASP.NET Core 手动埋点
• 使用 @azure/monitor-opentelemetry 进行 Node.js 手动埋点
• references/PYTHON.md 中提供了 Python 指南，尽管顶层 prerequisite 文案写得更窄一些

开始前最需要知道的限制

这个 skill 是明显 Azure 定向、且依赖托管环境判断的。如果你的应用不跑在 Azure 上，或者你只是想要偏厂商中立的 OpenTelemetry 架构建议，那么 appinsights-instrumentation for Observability 可能会显得过窄。它最有价值的前提，是代理能够检查你的应用和部署形态，并据此正确套用 Azure Monitor / App Insights 的约定。

如何使用 appinsights-instrumentation skill

安装背景与技能所在位置

这个 skill 来自 github/awesome-copilot 仓库下的 skills/appinsights-instrumentation。如果你的工具链支持安装 skill，就按你平时的 add-skill 流程添加这个仓库，然后在需要配置 Azure App Insights 时调用它。

由于这个仓库并不是围绕某个专用 CLI 来设计这个 skill，本质上的安装判断重点不在包管理，而在于你的工作区里是否具备以下信息：

• 应用源码
• 部署方式或托管环境线索
• Bicep、Terraform 等 IaC 文件
• 足够的 Azure 上下文，用来识别正在运行的应用

先给代理提供正确的上下文

想要获得高质量的 appinsights-instrumentation usage，不要一上来只说“加 App Insights”。更好的做法，是先提供这个 skill 真正在意的应用组合信息：

• 语言
• 框架
• 托管目标
• 部署方式
• 是否接受代码改动

更理想的首条请求可以是这样：

• “Instrument this ASP.NET Core app running in Azure App Service. Prefer codeless setup if supported. If not, update code and Bicep.”
• “This Node.js app is deployed to Azure App Service from this repo. Find the entry file, add Azure Monitor instrumentation, and show the env var changes needed.”
• “Inspect this repo and tell me whether auto-instrumentation is possible or whether manual App Insights instrumentation is required.”

这个 skill 最需要先确认的问题

仓库里写得很明确：代理首先应该判断应用到底托管在哪里。这个单一输入对整体方案的影响，比其他大多数信息都更大。如果你省略了托管信息，后续通常会多出一轮来回确认。

有用的托管答案包括：

• Azure App Service，代码直接部署
• Azure App Service，容器方式部署
• Azure Container Apps
• 仅本地运行
• 不确定，请从仓库和部署文件中推断

评估 appinsights-instrumentation install 时，优先看哪些仓库文件

如果你在评估 appinsights-instrumentation install 的实际质量，或者希望更好地引导代理，建议按这个顺序阅读文件：

1. SKILL.md
2. references/AUTO.md
3. references/ASPNETCORE.md
4. references/NODEJS.md
5. examples/appinsights.bicep
6. scripts/appinsights.ps1
7. references/PYTHON.md

这个顺序之所以有效，是因为：

• SKILL.md 负责给出路由逻辑
• AUTO.md 说明哪些情况下可以不改代码
• 各语言文档会给出精确的包和代码修改方式
• Bicep 示例能帮助你看清基础设施层需要改什么
• PowerShell 脚本则对应 Azure CLI 层面的 connection string 和配置项操作

如何在自动埋点和手动埋点之间做选择

可以按照下面的判断模式来做：

• 如果应用是跑在 Azure App Service 上的 ASP.NET Core 或 Node.js，先检查 auto-instrumentation。
• 如果 auto-instrumentation 不受支持、不符合你的要求，或者对你的部署流程来说过于黑盒，再切换到手动埋点。
• 如果团队用声明式方式管理基础设施，优先同时更新 IaC 和应用配置，而不是做一次性的 Portal 手工修改。

这是 appinsights-instrumentation guide 最实用的部分之一：它能帮你避免在其实没必要的代码修改上浪费时间。

ASP.NET Core 手动埋点工作流

针对 ASP.NET Core，仓库给出的指导是：

• 安装包：dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
• 添加 using Azure.Monitor.OpenTelemetry.AspNetCore;
• 在 builder.Build() 之前加入 builder.Services.AddOpenTelemetry().UseAzureMonitor();

然后，通过环境变量提供 App Insights connection string，而不是随手去改 appsettings。这个提醒非常关键，因为很多团队会不小心把配置硬编码进去，或者放在不适合部署环境继承的位置，最终上线后配置无法稳定生效。

Node.js 手动埋点工作流

对于 Node.js，实操流程通常是：

• 安装包：npm install @azure/monitor-opentelemetry
• 找到入口文件，通常从 package.json 的 main 字段判断
• 在靠近文件顶部的位置引入库：
  const { useAzureMonitor } = require("@azure/monitor-opentelemetry");
• 调用 useAzureMonitor();

这里的时序很重要：先加载环境变量，再调用 useAzureMonitor()，然后再加载应用其余部分。如果应用用了 dotenv，要先初始化 dotenv，再做 Azure Monitor 初始化。

App Insights 资源与 connection string 的处理

很多时候，真正卡住落地的不是代码埋点，而是资源接线。这个 skill 对两边都会覆盖：

• 创建或引用 Application Insights 资源
• 获取 connection string
• 设置 APPLICATIONINSIGHTS_CONNECTION_STRING
• 如果可能，把这个设置持久化到 IaC 中

仓库里同时提供了 examples/appinsights.bicep 和 scripts/appinsights.ps1，这很能说明问题：这个 skill 的设计目标不是只改源码文件，而是同时打通代码层和基础设施层。

更容易得到好结果的提示词模式

一个较弱的提示词是：

• “Add observability.”

更强的提示词可以是：

• “Use the appinsights-instrumentation skill on this repo. First detect whether this is ASP.NET Core, Node.js, or Python and how it is hosted. Prefer Azure App Service auto-instrumentation if supported. Otherwise, make the minimum code and IaC changes needed to send telemetry to Azure Application Insights. Show the exact files to edit and explain how to set APPLICATIONINSIGHTS_CONNECTION_STRING.”

为什么这样更好：

• 它强制代理先识别技术栈
• 它明确表达了“优先自动埋点”的偏好
• 它要求输出文件级别的修改
• 它把那个容易被忽略的环境变量要求也写进去了

拿到第一轮输出后，重点检查什么

代理给出方案后，在接受之前请先核对这些点：

• 它是否识别了托管环境，而不只是识别语言？
• 对于相关场景，它是否先检查了 Azure App Service auto-instrumentation？
• 它是否给出了该语言对应的正确包名？
• 初始化位置是否足够靠前，位于应用启动早期？
• 它是否把 connection string 作为环境变量处理？
• 如果仓库本来就用了 IaC，它是否建议同步修改 IaC？

如果这些内容缺失，那输出大概率还是泛化建议，而不是真正按 skill 逻辑推出来的方案。

appinsights-instrumentation skill 常见问题

appinsights-instrumentation 比普通提示词更好吗？

通常是的，前提是你的目标是在真实仓库里完成 Azure App Insights 接入。泛用提示词很容易漏掉托管环境相关的判断、auto-instrumentation 选项，或者 connection string 的具体处理流程。若你想减少 Azure 特有细节的遗漏，appinsights-instrumentation skill 往往更可靠。

这个 skill 对新手友好吗？

中等偏友好。它很实用，但默认你至少能回答一些基本部署问题，或者允许代理自行检查仓库。新手也能用好，只要能提供这些信息：

• 应用语言 / 框架
• Azure 托管类型
• 是否使用 App Service
• 基础设施是否通过代码管理

如果缺少这些信息，这个 skill 在产出可信方案之前，通常还需要先追问澄清。

它是不是只能用于 Azure App Service？

不是，但 Azure App Service 是它最有价值的决策场景，因为那里可能支持 auto-instrumentation。即便不走这条路径，这个 skill 仍然可以帮助你完成手动埋点、资源创建和 connection string 配置。

支持 Python 吗？

仓库里包含 references/PYTHON.md，说明确实有 Python 相关指导。不过，顶层 prerequisite 文案主要强调的是 ASP.NET Core 和 Node.js。更稳妥的理解是：Python 支持可以作为有用的参考路径，但在把它当作主场景之前，仍应先结合你自己的托管模型确认是否匹配。

什么情况下不该用 appinsights-instrumentation？

如果出现以下情况，就不太建议用 appinsights-instrumentation：

• 你的应用不托管在 Azure 上，而且你需要云无关的 observability 指导
• 你需要的是深度定制的 tracing 设计，而不是初始 App Insights 接入
• 你已经有成熟的 OpenTelemetry 埋点体系，只需要做小修小补
• 你的任务重点其实是 dashboard、alerting 或 KQL，而不是 instrumentation

这个 skill 会替我创建 Azure 资源吗？

它可以指导资源配置，并且会引用 examples/appinsights.bicep 这样的基础设施示例；但资源是否真的会被创建，取决于代理的权限和你的工作流。实际使用中，更合理的预期是：它帮你生成符合当前环境约束的精确 IaC 或 CLI 步骤。

如何改进 appinsights-instrumentation skill 的使用效果

先把完整的部署画像交给这个 skill

提升 appinsights-instrumentation usage 效果最快的方式，就是一开始就把部署画像说完整：

• 源码语言和框架
• Azure 托管服务
• 部署方式
• 是否存在 infra-as-code 文件
• 是否允许做 Portal 修改

这样可以减少这个 skill 最常见的失败模式：它选中的路径在技术上没错，但和你的实际运维模型并不匹配。

先让它做判断，再让它改文件

更高质量的工作流通常是：

1. 先让代理判断应用类型和托管方式
2. 再让它判断是否支持 auto-instrumentation
3. 只有在这之后，才要求它输出文件修改或 IaC patch

这样做的原因是，这个 skill 的主分支判断首先是架构层面的，不是语法层面的。

明确告诉代理该看哪些文件

如果仓库很大，最好直接告诉代理从哪里看起：

• ASP.NET Core 看 Program.cs
• Node.js 看 package.json 和入口文件
• 基础设施配置看 Bicep 或 Terraform 文件
• 托管线索看部署清单或工作流文件

这能减少它在错误的启动文件里做浅层修改，或漏掉真正应该放环境变量的 IaC 位置。

要求输出文件级 diff，而不是泛泛建议

如果想让 appinsights-instrumentation guide 的输出更可执行，最好明确要求：

• 具体修改哪些文件
• 具体的包安装命令
• 启动初始化代码的准确放置位置
• 环境变量的准确插入点
• App Insights 资源和应用设置在 IaC 里的准确新增内容

这样一来，这个 skill 就不只是给建议，而是能产出可落地的实施方案。

需要重点防范的常见失败模式

最常见的质量问题包括：

• 跳过托管环境检查
• 漏掉 auto-instrumentation 选项
• 在应用启动流程中过晚初始化 telemetry
• 把 connection string 配到了错误的位置
• 改了代码却忘了部署时配置
• 应用明明运行在 Azure，却把本地 app settings 当成事实来源

这些地方最值得做二次复核。

用更强的追问提示词提升输出质量

如果第一版回答太泛，可以直接用这种纠偏提示词：

• “Re-run appinsights-instrumentation with hosting-aware decisions. Confirm whether this Azure App Service app qualifies for auto-instrumentation before proposing code changes.”
• “Revise this plan to include the exact file edits, package command, and IaC changes for APPLICATIONINSIGHTS_CONNECTION_STRING.”
• “Compare manual instrumentation vs auto-instrumentation for this repo and recommend one based on the deployment files present.”

验证的不只是能编译，还要验证 observability 真的生效

成功不应只停留在应用能 build。你还应该让代理说明，如何确认 telemetry 真的已经打通：

• connection string 从哪里提供
• 哪个部署步骤会把这个设置应用上去
• 哪个请求或启动行为应该触发 telemetry
• 部署后你在 Azure 侧应该看到什么信号

这会让 appinsights-instrumentation for Observability 在生产环境里更有价值，因为静默配置错误其实很常见。

在实践中扩展 appinsights-instrumentation 的最佳方式

如果你想长期从这个 skill 获得更多价值，最有效的办法其实是把自己的提示词模式也一起固定下来：

• 始终提供托管信息
• 始终要求比较自动埋点和手动埋点
• 始终同时要求基础设施改动和代码改动
• 始终要求给出部署后的验证清单

这种模式和仓库本身的结构高度一致，得到的结果通常会远好于一句话式请求。