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