appinsights-instrumentation

appinsights-instrumentation 技能總覽

appinsights-instrumentation 技能可協助代理程式為 Web 應用加入 Azure Application Insights 遙測，比起泛用型 observability 提示更少靠猜測。它真正的價值不只是「把 log 打開」，而是依照應用的語言與託管模式選出正確的 instrumentation 路徑、建立或串接 App Insights 資源，並確保應用取得必要的 APPLICATIONINSIGHTS_CONNECTION_STRING。

這個技能最適合哪些人

如果你在 Azure 上有 Web 應用，想要有人實際協助把 observability 做好，appinsights-instrumentation 會很適合，尤其是以下情境：

• 託管於 Azure 的 ASP.NET Core 應用
• 託管於 Azure 的 Node.js 應用
• 使用 Azure App Service 的團隊
• 已經採用 Bicep 等 IaC，並希望把遙測整潔地納入現有基礎架構流程的 repo

當你希望代理程式先檢查 repo、推斷 framework 細節，再建議該用 auto-instrumentation 還是修改程式碼時，這個技能也很有用。

使用者最先在意的是什麼

在安裝 appinsights-instrumentation 之前，多數使用者最想先確認的是：

• 它能不能套用到我的應用技術棧？
• 我可不可以避免改程式碼？
• 需要改哪些檔案？
• 我要怎麼建立或找到 App Insights 的 connection string？
• 我應該更新 infrastructure code，還是手動補設定就好？

相較於籠統的「加入 observability」指令，這個技能更直接回應了這些導入前最常見的阻力。

主要差異：auto instrumentation 與 manual instrumentation

appinsights-instrumentation skill 最大的價值，在於它不會把所有應用一視同仁。它會明確優先考慮支援的 Azure App Service auto-instrumentation，必要時才退回手動修改程式碼的路線。

這點很重要，因為許多使用者若 Azure App Service 本身已支援，通常更希望在不碰應用程式碼的情況下啟用遙測。

從 repository 可看出的支援路徑

根據 repository 內容，實際可行的路徑包括：

• 適用於支援情境的 ASP.NET Core 與 Node.js 應用之 Azure App Service auto-instrumentation
• 使用 Azure.Monitor.OpenTelemetry.AspNetCore 的 ASP.NET Core 手動 instrumentation
• 使用 @azure/monitor-opentelemetry 的 Node.js 手動 instrumentation
• references/PYTHON.md 中提供的 Python 指引，雖然最上層 prerequisite 說明的範圍較窄

一開始就要知道的主要限制

這個技能是 Azure 專用，而且會依託管環境做判斷。若你的應用不是部署在 Azure，或你只想要與廠商無關的 OpenTelemetry 架構建議，那麼 appinsights-instrumentation for Observability 可能會顯得太窄。它最有價值的情況，是代理程式能夠檢查你的應用與部署型態，並正確套用 Azure Monitor / App Insights 的慣例。

如何使用 appinsights-instrumentation 技能

安裝脈絡與這個技能位於哪裡

這個技能來自 github/awesome-copilot 中的 skills/appinsights-instrumentation。如果你的工具支援技能安裝，就用該 repository 平常的 add-skill 流程安裝，之後在請求 Azure App Insights 設定時呼叫這個技能。

由於這個 repository 並不是圍繞這個技能專屬的自訂 CLI 設計，安裝時真正需要判斷的，與其說是 package management，不如說是你的 workspace 是否包含：

• 應用原始碼
• 部署或託管相關線索
• 像 Bicep 或 Terraform 這類 IaC 檔案
• 足夠辨識實際執行中應用的 Azure 脈絡

一開始就給代理程式正確脈絡

要讓 appinsights-instrumentation 發揮效果，不要一開始只說「加上 App Insights」。應先提供這個技能最在乎的應用組合資訊：

• 語言
• framework
• 託管目標
• 部署方式
• 是否能接受程式碼修改

一個好的起手式會像這樣：

• 「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.」

這個技能最需要先回答的問題

repository 說得很明白：代理程式應該永遠先判斷應用實際託管在哪裡。這一個輸入，比其他條件更會直接改變整個方案。如果你省略託管資訊，通常就得來回補問。

有用的託管答案包括：

• Azure App Service as code deployment
• Azure App Service as container
• Azure Container Apps
• 僅在本機執行
• 不確定，請從 repo 與部署檔案推斷

最值得優先閱讀的 repository 檔案

如果你正在評估 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 說明何時不需要改程式碼
• 各語言檔案列出了精確的 package 與程式碼修改方式
• Bicep 範例可釐清基礎架構層需要做哪些變更
• PowerShell script 則對應到 connection string 與設定值相關的 Azure CLI 操作

如何在 auto instrumentation 與 manual instrumentation 之間做選擇

可用以下決策模式：

• 如果應用是跑在 Azure App Service 上的 ASP.NET Core 或 Node.js，先檢查是否支援 auto-instrumentation。
• 如果 auto-instrumentation 不支援、不符合需求，或對你的部署流程來說太不透明，再改走 manual instrumentation。
• 如果你的團隊以宣告式方式管理 infra，通常比起一次性在 portal 手改，更應該同步更新 IaC 與 app config。

這是 appinsights-instrumentation guide 最實用的部分之一：它能避免在其實不需要的情況下浪費時間修改程式碼。

ASP.NET Core 的手動流程

對 ASP.NET Core 而言，repository 指向的做法是：

• 安裝 package：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 而言，實際流程是：

• 安裝 package：npm install @azure/monitor-opentelemetry
• 找出 entry file，通常可從 package.json 的 main 欄位判斷
• 在接近檔案頂部的位置 require 這個函式庫：
  const { useAzureMonitor } = require("@azure/monitor-opentelemetry");
• 呼叫 useAzureMonitor();

初始化時機很重要：先載入環境變數，再呼叫 useAzureMonitor()，然後才載入其餘應用程式。如果應用使用 dotenv，就應該先初始化 dotenv，再做 Azure Monitor 設定。

App Insights 資源與 connection string 的處理方式

很多導入上的卡點，不是出在程式碼 instrumentation，而是資源串接。這個技能同時涵蓋兩邊：

• 建立或引用 Application Insights 資源
• 取回 connection string
• 設定 APPLICATIONINSIGHTS_CONNECTION_STRING
• 能用 IaC 持久化時就優先寫進 IaC

repo 內含 examples/appinsights.bicep 與 scripts/appinsights.ps1，這很明顯表示這個技能不是只打算改 source file，而是要同時涵蓋程式碼與基礎架構兩層。

哪種提示寫法會得到更好的結果

一個弱的 prompt：

• 「Add observability.」

更好的 prompt：

• 「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.」

它之所以更好，是因為：

• 它強制先判斷技術棧
• 它明確表達 auto-first 的偏好
• 它要求提供檔案層級的修改
• 它把容易被忽略的 env var 要求一起寫進去

第一輪輸出後要檢查什麼

代理程式回覆後，在接受方案前先確認以下項目：

• 它是否辨識了託管環境，而不只是語言？
• 在適用情況下，它是否先檢查 Azure App Service auto-instrumentation？
• 它是否指定了對應語言的正確 package？
• 它是否把初始化放在足夠早的 app startup 階段？
• 它是否把 connection string 當成 environment variable 處理？
• 如果 repo 已使用 IaC，它是否也提出了 IaC 變更建議？

如果這些都缺少，輸出內容多半只是泛泛建議，而不是真的依技能邏輯產生。

appinsights-instrumentation 技能 FAQ

appinsights-instrumentation 會比一般 prompt 更好嗎？

通常會，前提是你的目標是在真實 repo 中完成 Azure App Insights 設定。泛用 prompt 很容易漏掉依託管環境而變的判斷、auto-instrumentation 選項，或 connection string 的正確處理流程。當你想避免 Azure 特有細節被遺漏時，appinsights-instrumentation skill 通常更可靠。

這個技能對新手友善嗎？

算是中等。它很實務，但預設你至少能回答基本部署問題，或讓代理程式自行檢查 repo。新手仍然可以用得不錯，只要先提供：

• 應用語言／framework
• Azure 託管類型
• 是否使用 App Service
• infrastructure 是否以程式碼管理

如果沒有這些資訊，技能通常得先追問，才能產出值得信任的方案。

它只適用於 Azure App Service 嗎？

不是，但它最有價值的決策邏輯，確實主要出現在 Azure App Service，因為那裡可能支援 auto-instrumentation。離開這條路徑後，這個技能仍可協助處理手動 instrumentation、資源建立與 connection string 設定。

支援 Python 嗎？

repo 內含 references/PYTHON.md，表示有 Python 相關指引。不過最上層 prerequisite 說明仍主要聚焦在 ASP.NET Core 與 Node.js。比較合理的看法是：Python 支援可作為有用的參考路徑，但在把它當成主要使用情境前，仍應先對照你的實際託管模式確認是否適合。

什麼情況下不該使用 appinsights-instrumentation？

以下情況建議跳過 appinsights-instrumentation：

• 你的應用不是託管在 Azure，且你要的是雲端中立的 observability 指引
• 你需要的是深度的自訂 tracing 設計，而不是先把 App Insights 啟用起來
• 你已經有成熟的 OpenTelemetry instrumentation，只差少量微調
• 你的任務主要是 dashboarding、alerting 或 KQL，而不是 instrumentation

這個技能會幫我建立 Azure 資源嗎？

它可以引導資源設定，並指向像 examples/appinsights.bicep 這類基礎架構範例，但實際會不會建立資源，仍取決於代理程式權限與你的工作流程。實務上，最好的使用方式通常是讓它產出你當前環境可執行的精確 IaC 或 CLI 步驟。

如何改善 appinsights-instrumentation 技能的使用效果

先把完整部署圖像交給技能

想提升 appinsights-instrumentation 的使用效果，最快的方法就是一開始就給完整部署圖像：

• 原始語言與 framework
• Azure 託管服務
• 部署方式
• 是否存在 infra-as-code 檔案
• 是否允許 portal 手動修改

這能降低這個技能最常見的失敗模式：它走了一條技術上可行、但與你實際營運模式不相符的路。

先要求做判斷，再要求修改

較高品質的工作流程通常是：

1. 先請代理程式分類應用與託管方式
2. 再問是否支援 auto-instrumentation
3. 最後才要求檔案修改或 IaC patch

這樣做會讓輸出更好，因為這個技能最主要的分支點是架構判斷，不是語法細節。

明確指出要看哪些檔案

如果 repo 很大，直接告訴代理程式該看哪裡：

• ASP.NET Core 看 Program.cs
• Node.js 看 package.json 與 entry file
• infra 設定看 Bicep 或 Terraform 檔案
• 託管線索看 deployment manifest 或 workflow

這能避免它在錯的 startup file 上做表層修改，或漏掉真正應該放 env var 的 IaC 位置。

要求檔案層級 diff，而不是泛泛建議

想讓 appinsights-instrumentation guide 的輸出更有落地性，可以直接要求：

• 需要修改的精確檔案
• 精確的 package 安裝指令
• 精確的 startup 初始化位置
• 精確的 environment variable 插入點
• 為 App Insights 資源與 app settings 增加的精確 IaC 內容

這會讓技能從「諮詢建議」變成真正可執行的實作方案。

常見失敗模式要特別留意

最常見的品質問題包括：

• 略過託管環境檢查
• 漏掉 auto-instrumentation 選項
• 在 app startup 過晚才初始化 telemetry
• 把 connection string 設在錯的位置
• 改了程式碼卻忘了部署時設定
• 應用明明跑在 Azure，卻把本機 app settings 當成唯一真實來源

這些地方最值得做第二次審查。

用更強的追問 prompt 改善輸出

如果第一版答案太泛，可以用這類修正 prompt：

• 「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 來源在哪裡
• 哪個 deployment 步驟會套用該設定
• 哪個 request 或 startup 活動應該會產生 telemetry
• 部署後在 Azure 端應該看到什麼訊號

這會讓 appinsights-instrumentation for Observability 在正式環境中更有價值，因為靜默式設定錯誤其實很常見。

實務上延伸 appinsights-instrumentation 的最佳方式

如果你希望這個技能長期帶來更多價值，最實際的做法是把自己的 prompt 模式一起標準化：

• 永遠附上託管細節
• 永遠要求 auto 與 manual 的比較
• 永遠同時要求 infra 與 code 變更
• 永遠要求部署後驗證清單

這種用法和 repository 的結構高度一致，通常也比一句話的簡短請求得到好得多的結果。