1. 分布式调试的痛点日志太多链路太长如果你写过 .NET Aspire 项目大概率经历过这种场景本地 F5 启动 AppHostDashboard 一打开资源列表里五六个服务全绿但某个 API 偶尔返回 500。点进 Structured logs几百条日志刷屏Error 和 Warning 混在一起再切到 Traces一条跨 OrderService、PaymentService、Redis 的调用链展开有二十多个 span哪个环节慢、哪个环节抛异常全靠肉眼一行行对时间戳。我试过最笨的办法把 TraceId 复制出来在日志页搜索框里粘贴再一条条看。问题是 Aspire Dashboard 的日志和追踪是两个独立视图来回跳转特别费神。更麻烦的是很多异常不是本地代码直接抛的而是下游服务超时、gRPC 状态码非 OK、HttpClient 连接被拒绝这些信息散落在不同 span 的 attributes 里人工关联成本极高。.NET Aspire 9.3 之后Dashboard 右上角多了一个 GitHub Copilot 按钮资源、结构化日志、追踪、Span 的右键菜单里也出现了「Ask GitHub Copilot」。它做的事情很直接把当前视图里的 OpenTelemetry 数据日志、trace、span、resource 状态作为上下文喂给 Copilot让 AI 帮你做归纳、定位和解释。对本地调试来说这相当于给 Dashboard 配了一个随时能问的 SRE 助手。这篇文章聚焦本地调试场景交付三样东西可复制的 AppHost 配置片段确保遥测数据完整上报到 Dashboard、Copilot 提示词模板针对日志分析和追踪分析分别给模板、以及验证遥测是否被正确采集的步骤。适合正在用 .NET Aspire 做微服务本地开发、已经被分布式日志折磨过的 .NET 开发者。2. 前置准备TaoToken 与 Copilot 在 Aspire 里的分工先说清楚一件事Aspire Dashboard 里的 GitHub Copilot 集成走的是你 IDE 登录的 GitHub 账号和 Copilot 订阅它负责「读 Dashboard 里的遥测数据并给出分析建议」。而如果你在项目里用 AI 辅助写代码、生成 AppHost 配置、或者跑 Agent 做批量重构这部分模型调用可以走 TaoToken 的 API两者不冲突。TaoToken 在这里的角色是统一的模型接入层官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以了解能力范围API 入口是 https://taotoken.net/api不加 UTM。如果你要在 AppHost 或配套脚本里调用模型做日志摘要、生成提示词用它的 API Key 就行。需要提前准备的东西.NET Aspire 9.3 或更高版本的 AppHost 项目VS Code C# Dev Kit 1.19.63或 Visual Studio 17.14IDE 里已登录 GitHub 账号且该账号有 Copilot 订阅免费计划也行有每月聊天次数限制一个能正常跑的 Aspire 项目至少包含两个以上资源比如 API Worker Redis注意Dashboard 里的 Copilot 只在从 IDE 运行 Aspire 项目时可用直接dotnet run启动 AppHost 不会出现 Copilot 按钮。这是设计如此不是配置问题。如果你还没有 API Key可以去控制台创建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 任务的话Coding Plan 页面是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。3. 可复制配置让 AppHost 把遥测完整送到 DashboardCopilot 能不能给出准确建议前提是 Dashboard 里得有足够完整的 OpenTelemetry 数据。Aspire 默认已经开了 OTLP 导出但有些细节不配好日志和 trace 会缺字段。下面这段 AppHost 配置可以直接抄。3.1 AppHost Program.cs 基础配置var builder DistributedApplication.CreateBuilder(args); // Redis 作为缓存资源方便演示跨服务调用链 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();这段是标准写法重点是WithReference会把连接字符串和服务发现信息注入到下游项目同时 Aspire 会自动为每个项目配置 OTLP exporter把日志、trace、metrics 发到 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很关键否则 span 里只有状态码没有异常类型和堆栈Copilot 分析时只能看到「500」而看不到「为什么 500」。3.3 结构化日志里带上 TraceId在业务代码里打日志时用ILogger的结构化写法Aspire 会自动把 TraceId 和 SpanId 关联进去public async TaskOrderResult CreateOrderAsync(OrderRequest request, CancellationToken ct) { using var activity Activity.Current?.Source.StartActivity(CreateOrder); activity?.SetTag(order.id, request.OrderId); _logger.LogInformation(开始创建订单 {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} 创建失败, request.OrderId); throw; } }这样在 Dashboard 的 Structured logs 里每条日志都能点开看到对应的 TraceIdCopilot 也能顺着这个关联去分析整条链路。4. 验证请求确认遥测数据被 Dashboard 正确采集配置写完启动项目按下面步骤验证数据是否到位。这一步不做后面 Copilot 分析出来的结论可能是残缺的。4.1 启动并检查资源状态从 IDE 按 F5 启动 AppHostDashboard 自动打开。资源列表里应该看到 apiservice、workerservice、webfrontend、cache 全部变成 Running 状态。如果某个资源一直 Starting先看它的日志通常是端口冲突或依赖没起来。4.2 触发一次跨服务调用用浏览器或 curl 打一下 webfrontend 的接口让它调用 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 页面应该能看到一条 trace展开后包含webfrontend 的 HTTP server spanapiservice 的 HTTP client span 和 server spanRedis 的 command span如果 worker 被触发还有 worker 的消费 span每个 span 的 Duration、Status、Attributes 都要有值。如果某个 span 缺失回到第 3.2 节检查对应的 Instrumentation 有没有加。4.4 在 Structured logs 页面确认 TraceId 关联切到 Structured logs找到刚才那条「开始创建订单」的日志点开详情应该能看到 TraceId 和 SpanId 字段。复制 TraceId回到 Traces 页面搜索能定位到同一条链路。这个关联是 Copilot 做跨视图分析的基础。4.5 确认 Copilot 按钮出现Dashboard 右上角应该出现 GitHub Copilot 图标。如果没有检查IDE 是否登录了 GitHub 账号、账号是否有 Copilot 订阅、C# Dev Kit 版本是否达标。资源、日志、追踪的右键菜单里也应该有「Ask GitHub Copilot」选项。5. Copilot 提示词模板与常见错排查数据验证通过后就可以用 Copilot 做实际分析了。下面给两类提示词模板以及我踩过的几个坑。5.1 日志分析提示词模板在 Structured logs 页面选中一批 Error 日志右键「Ask GitHub Copilot」然后输入请分析当前选中的错误日志按以下结构输出 1. 错误类型归纳相同根因的合并 2. 每条错误的可能触发条件 3. 涉及的服务和 TraceId 4. 建议的排查顺序从最可能的根因开始 不要逐条复述日志原文只给归纳和判断。这个模板的好处是强制 Copilot 做归纳而不是复读。实测下来几百条日志它能压成三到五条根因比人工翻快很多。5.2 追踪分析提示词模板在 Trace 详情页点「解析跟踪」或者右键「Ask GitHub Copilot」输入请分析这条分布式追踪 1. 关键路径上耗时最长的三个 span给出耗时占比 2. 是否有失败或异常的 span指出异常类型和所在服务 3. 是否存在串行调用可以并行化的机会 4. 如果这是性能问题最可能的瓶颈在哪 用表格列出 span 名称、服务、耗时、状态。5.3 常见错排查Copilot 按钮不出现最常见原因是没从 IDE 启动或者 C# Dev Kit 版本低于 1.19.63。VS Code 里检查扩展版本升级后重启。Copilot 分析结果说「没有足够上下文」通常是遥测数据缺字段。回到第 4 节确认 span 的 Attributes 和日志的 TraceId 都有值。特别是RecordException没开的话异常 span 里只有状态码Copilot 没法判断根因。日志里 TraceId 为空检查是否用了结构化日志写法。字符串拼接的日志比如LogInformation(order id)不会自动关联 TraceId必须用占位符写法LogInformation(order {OrderId}, id)。Traces 页面只有 server span 没有 client spanHttpClientInstrumentation 没加或者 HttpClient 是直接new出来的而不是通过 DI 注入的。Aspire 里统一用AddHttpClient注册。Copilot 给出的建议和实际代码对不上Dashboard 里的 Copilot 只能看到遥测数据看不到你的源码。如果分析涉及具体代码逻辑需要你手动把相关代码片段贴进对话或者用 IDE 里的 Copilot Chat 结合代码上下文问。5.4 把 AI 分析接入日常调试流程如果你想把日志摘要、trace 分析做成自动化脚本比如每次 CI 跑完集成测试后自动生成一份诊断报告可以用 TaoToken 的 API 来调模型。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API 入口 https://taotoken.net/api 。脚本里把 Dashboard 导出的 OTLP 数据或日志文件作为上下文传给模型就能批量生成分析结果。长期跑这类任务的话Coding Plan 比按次调用更划算页面在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。6. 把 Copilot 变成你的 Aspire 调试搭档Aspire Dashboard 集成 Copilot 之后本地调试的流程可以变成这样先按第 3 节配好遥测按第 4 节验证数据完整遇到问题时不再手动翻日志而是选中相关日志或 trace用第 5 节的模板让 Copilot 做归纳和定位。它不能替代你对业务代码的理解但能把你从「几百条日志里找异常」这种体力活里解放出来。几个实用技巧提示词里明确要求「按根因归纳」而不是「逐条列出」输出质量会高很多分析 trace 时先让它算耗时占比再问瓶颈比直接问「哪里慢」更准如果 Copilot 的结论你觉得不对把对应的 span attributes 或日志字段贴回去追问通常能纠正。如果你在项目里同时用 AI 辅助编码和调试分析可以把模型调用统一走 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 相关的接入可以参考 https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。