1. 分布式調(diào)試的痛點日志太多鏈路太長如果你寫過 .NET Aspire 項目大概率經(jīng)歷過這種場景本地 F5 啟動 AppHostDashboard 一打開資源列表里五六個服務(wù)全綠但某個 API 偶爾返回 500。點進 Structured logs幾百條日志刷屏Error 和 Warning 混在一起再切到 Traces一條跨 OrderService、PaymentService、Redis 的調(diào)用鏈展開有二十多個 span哪個環(huán)節(jié)慢、哪個環(huán)節(jié)拋異常全靠肉眼一行行對時間戳。我試過最笨的辦法把 TraceId 復(fù)制出來在日志頁搜索框里粘貼再一條條看。問題是 Aspire Dashboard 的日志和追蹤是兩個獨立視圖來回跳轉(zhuǎn)特別費神。更麻煩的是很多異常不是本地代碼直接拋的而是下游服務(wù)超時、gRPC 狀態(tài)碼非 OK、HttpClient 連接被拒絕這些信息散落在不同 span 的 attributes 里人工關(guān)聯(lián)成本極高。.NET Aspire 9.3 之后Dashboard 右上角多了一個 GitHub Copilot 按鈕資源、結(jié)構(gòu)化日志、追蹤、Span 的右鍵菜單里也出現(xiàn)了「Ask GitHub Copilot」。它做的事情很直接把當(dāng)前視圖里的 OpenTelemetry 數(shù)據(jù)日志、trace、span、resource 狀態(tài)作為上下文喂給 Copilot讓 AI 幫你做歸納、定位和解釋。對本地調(diào)試來說這相當(dāng)于給 Dashboard 配了一個隨時能問的 SRE 助手。這篇文章聚焦本地調(diào)試場景交付三樣?xùn)|西可復(fù)制的 AppHost 配置片段確保遙測數(shù)據(jù)完整上報到 Dashboard、Copilot 提示詞模板針對日志分析和追蹤分析分別給模板、以及驗證遙測是否被正確采集的步驟。適合正在用 .NET Aspire 做微服務(wù)本地開發(fā)、已經(jīng)被分布式日志折磨過的 .NET 開發(fā)者。2. 前置準(zhǔn)備TaoToken 與 Copilot 在 Aspire 里的分工先說清楚一件事Aspire Dashboard 里的 GitHub Copilot 集成走的是你 IDE 登錄的 GitHub 賬號和 Copilot 訂閱它負責(zé)「讀 Dashboard 里的遙測數(shù)據(jù)并給出分析建議」。而如果你在項目里用 AI 輔助寫代碼、生成 AppHost 配置、或者跑 Agent 做批量重構(gòu)這部分模型調(diào)用可以走 TaoToken 的 API兩者不沖突。TaoToken 在這里的角色是統(tǒng)一的模型接入層官網(wǎng) https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以了解能力范圍API 入口是 https://taotoken.net/api不加 UTM。如果你要在 AppHost 或配套腳本里調(diào)用模型做日志摘要、生成提示詞用它的 API Key 就行。需要提前準(zhǔn)備的東西.NET Aspire 9.3 或更高版本的 AppHost 項目VS Code C# Dev Kit 1.19.63或 Visual Studio 17.14IDE 里已登錄 GitHub 賬號且該賬號有 Copilot 訂閱免費計劃也行有每月聊天次數(shù)限制一個能正常跑的 Aspire 項目至少包含兩個以上資源比如 API Worker Redis注意Dashboard 里的 Copilot 只在從 IDE 運行 Aspire 項目時可用直接dotnet run啟動 AppHost 不會出現(xiàn) Copilot 按鈕。這是設(shè)計如此不是配置問題。如果你還沒有 API Key可以去控制臺創(chuàng)建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理頁在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。模型對話入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 接入文檔在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。長期做編碼和 Agent 任務(wù)的話Coding Plan 頁面是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。3. 可復(fù)制配置讓 AppHost 把遙測完整送到 DashboardCopilot 能不能給出準(zhǔn)確建議前提是 Dashboard 里得有足夠完整的 OpenTelemetry 數(shù)據(jù)。Aspire 默認已經(jīng)開了 OTLP 導(dǎo)出但有些細節(jié)不配好日志和 trace 會缺字段。下面這段 AppHost 配置可以直接抄。3.1 AppHost Program.cs 基礎(chǔ)配置var builder DistributedApplication.CreateBuilder(args); // Redis 作為緩存資源方便演示跨服務(wù)調(diào)用鏈 var cache builder.AddRedis(cache); var apiService builder.AddProjectProjects.AspireCopilotDemo_ApiService(apiservice) .WithReference(cache) .WithHttpHealthCheck(/health); var workerService builder.AddProjectProjects.AspireCopilotDemo_Worker(workerservice) .WithReference(cache) .WithReference(apiService); builder.AddProjectProjects.AspireCopilotDemo_Web(webfrontend) .WithExternalHttpEndpoints() .WithReference(apiService) .WithReference(workerService); builder.Build().Run();這段是標(biāo)準(zhǔn)寫法重點是WithReference會把連接字符串和服務(wù)發(fā)現(xiàn)信息注入到下游項目同時 Aspire 會自動為每個項目配置 OTLP exporter把日志、trace、metrics 發(fā)到 Dashboard。3.2 確保日志和追蹤字段完整在 ApiService 和 Worker 的Program.cs里建議顯式配置 OpenTelemetry把異常堆棧和 HTTP/gRPC 的 span 屬性帶上builder.Services.AddOpenTelemetry() .WithTracing(tracing { tracing.AddAspNetCoreInstrumentation(options { options.RecordException true; options.EnrichWithHttpRequestMessage (activity, request) { activity.SetTag(http.request.body.size, request.Content?.Headers.ContentLength); }; }); tracing.AddHttpClientInstrumentation(options { options.RecordException true; }); tracing.AddGrpcClientInstrumentation(); tracing.AddRedisInstrumentation(); }) .WithLogging(logging { logging.AddOtlpExporter(); });RecordException true很關(guān)鍵否則 span 里只有狀態(tài)碼沒有異常類型和堆棧Copilot 分析時只能看到「500」而看不到「為什么 500」。3.3 結(jié)構(gòu)化日志里帶上 TraceId在業(yè)務(wù)代碼里打日志時用ILogger的結(jié)構(gòu)化寫法Aspire 會自動把 TraceId 和 SpanId 關(guān)聯(lián)進去public async TaskOrderResult CreateOrderAsync(OrderRequest request, CancellationToken ct) { using var activity Activity.Current?.Source.StartActivity(CreateOrder); activity?.SetTag(order.id, request.OrderId); _logger.LogInformation(開始創(chuàng)建訂單 {OrderId}金額 {Amount}, request.OrderId, request.Amount); try { var result await _paymentClient.ChargeAsync(request, ct); _logger.LogInformation(訂單 {OrderId} 支付成功交易號 {TransactionId}, request.OrderId, result.TransactionId); return result; } catch (Exception ex) { _logger.LogError(ex, 訂單 {OrderId} 創(chuàng)建失敗, request.OrderId); throw; } }這樣在 Dashboard 的 Structured logs 里每條日志都能點開看到對應(yīng)的 TraceIdCopilot 也能順著這個關(guān)聯(lián)去分析整條鏈路。4. 驗證請求確認遙測數(shù)據(jù)被 Dashboard 正確采集配置寫完啟動項目按下面步驟驗證數(shù)據(jù)是否到位。這一步不做后面 Copilot 分析出來的結(jié)論可能是殘缺的。4.1 啟動并檢查資源狀態(tài)從 IDE 按 F5 啟動 AppHostDashboard 自動打開。資源列表里應(yīng)該看到 apiservice、workerservice、webfrontend、cache 全部變成 Running 狀態(tài)。如果某個資源一直 Starting先看它的日志通常是端口沖突或依賴沒起來。4.2 觸發(fā)一次跨服務(wù)調(diào)用用瀏覽器或 curl 打一下 webfrontend 的接口讓它調(diào)用 apiserviceapiservice 再訪問 Rediscurl -X POST http://localhost:5000/api/orders \ -H Content-Type: application/json \ -d {orderId:ORD-1001,amount:99.9}4.3 在 Traces 頁面確認鏈路完整切到 Dashboard 的 Traces 頁面應(yīng)該能看到一條 trace展開后包含webfrontend 的 HTTP server spanapiservice 的 HTTP client span 和 server spanRedis 的 command span如果 worker 被觸發(fā)還有 worker 的消費 span每個 span 的 Duration、Status、Attributes 都要有值。如果某個 span 缺失回到第 3.2 節(jié)檢查對應(yīng)的 Instrumentation 有沒有加。4.4 在 Structured logs 頁面確認 TraceId 關(guān)聯(lián)切到 Structured logs找到剛才那條「開始創(chuàng)建訂單」的日志點開詳情應(yīng)該能看到 TraceId 和 SpanId 字段。復(fù)制 TraceId回到 Traces 頁面搜索能定位到同一條鏈路。這個關(guān)聯(lián)是 Copilot 做跨視圖分析的基礎(chǔ)。4.5 確認 Copilot 按鈕出現(xiàn)Dashboard 右上角應(yīng)該出現(xiàn) GitHub Copilot 圖標(biāo)。如果沒有檢查IDE 是否登錄了 GitHub 賬號、賬號是否有 Copilot 訂閱、C# Dev Kit 版本是否達標(biāo)。資源、日志、追蹤的右鍵菜單里也應(yīng)該有「Ask GitHub Copilot」選項。5. Copilot 提示詞模板與常見錯排查數(shù)據(jù)驗證通過后就可以用 Copilot 做實際分析了。下面給兩類提示詞模板以及我踩過的幾個坑。5.1 日志分析提示詞模板在 Structured logs 頁面選中一批 Error 日志右鍵「Ask GitHub Copilot」然后輸入請分析當(dāng)前選中的錯誤日志按以下結(jié)構(gòu)輸出 1. 錯誤類型歸納相同根因的合并 2. 每條錯誤的可能觸發(fā)條件 3. 涉及的服務(wù)和 TraceId 4. 建議的排查順序從最可能的根因開始 不要逐條復(fù)述日志原文只給歸納和判斷。這個模板的好處是強制 Copilot 做歸納而不是復(fù)讀。實測下來幾百條日志它能壓成三到五條根因比人工翻快很多。5.2 追蹤分析提示詞模板在 Trace 詳情頁點「解析跟蹤」或者右鍵「Ask GitHub Copilot」輸入請分析這條分布式追蹤 1. 關(guān)鍵路徑上耗時最長的三個 span給出耗時占比 2. 是否有失敗或異常的 span指出異常類型和所在服務(wù) 3. 是否存在串行調(diào)用可以并行化的機會 4. 如果這是性能問題最可能的瓶頸在哪 用表格列出 span 名稱、服務(wù)、耗時、狀態(tài)。5.3 常見錯排查Copilot 按鈕不出現(xiàn)最常見原因是沒從 IDE 啟動或者 C# Dev Kit 版本低于 1.19.63。VS Code 里檢查擴展版本升級后重啟。Copilot 分析結(jié)果說「沒有足夠上下文」通常是遙測數(shù)據(jù)缺字段?；氐降?4 節(jié)確認 span 的 Attributes 和日志的 TraceId 都有值。特別是RecordException沒開的話異常 span 里只有狀態(tài)碼Copilot 沒法判斷根因。日志里 TraceId 為空檢查是否用了結(jié)構(gòu)化日志寫法。字符串拼接的日志比如LogInformation(order id)不會自動關(guān)聯(lián) TraceId必須用占位符寫法LogInformation(order {OrderId}, id)。Traces 頁面只有 server span 沒有 client spanHttpClientInstrumentation 沒加或者 HttpClient 是直接new出來的而不是通過 DI 注入的。Aspire 里統(tǒng)一用AddHttpClient注冊。Copilot 給出的建議和實際代碼對不上Dashboard 里的 Copilot 只能看到遙測數(shù)據(jù)看不到你的源碼。如果分析涉及具體代碼邏輯需要你手動把相關(guān)代碼片段貼進對話或者用 IDE 里的 Copilot Chat 結(jié)合代碼上下文問。5.4 把 AI 分析接入日常調(diào)試流程如果你想把日志摘要、trace 分析做成自動化腳本比如每次 CI 跑完集成測試后自動生成一份診斷報告可以用 TaoToken 的 API 來調(diào)模型。接入文檔在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API 入口 https://taotoken.net/api 。腳本里把 Dashboard 導(dǎo)出的 OTLP 數(shù)據(jù)或日志文件作為上下文傳給模型就能批量生成分析結(jié)果。長期跑這類任務(wù)的話Coding Plan 比按次調(diào)用更劃算頁面在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。6. 把 Copilot 變成你的 Aspire 調(diào)試搭檔Aspire Dashboard 集成 Copilot 之后本地調(diào)試的流程可以變成這樣先按第 3 節(jié)配好遙測按第 4 節(jié)驗證數(shù)據(jù)完整遇到問題時不再手動翻日志而是選中相關(guān)日志或 trace用第 5 節(jié)的模板讓 Copilot 做歸納和定位。它不能替代你對業(yè)務(wù)代碼的理解但能把你從「幾百條日志里找異?！惯@種體力活里解放出來。幾個實用技巧提示詞里明確要求「按根因歸納」而不是「逐條列出」輸出質(zhì)量會高很多分析 trace 時先讓它算耗時占比再問瓶頸比直接問「哪里慢」更準(zhǔn)如果 Copilot 的結(jié)論你覺得不對把對應(yīng)的 span attributes 或日志字段貼回去追問通常能糾正。如果你在項目里同時用 AI 輔助編碼和調(diào)試分析可以把模型調(diào)用統(tǒng)一走 TaoTokenAPI Key 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 管理模型對話在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 體驗。Claude Code 相關(guān)的接入可以參考 https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。