分布式追踪与 OpenTelemetry 实战指南为 .NET 微服务构建端到端可观测性【免费下载链接】awesome-software-architecture A curated list of awesome articles, videos, and other resources to learn and practice software architecture, patterns, and principles.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-software-architecture本篇技术指南以开源仓库 awesome-software-architecture 中 分布式追踪专题文档 为核心骨架系统讲解分布式追踪Distributed Tracing与 OpenTelemetry 的核心概念、上下文传播机制、语义约定、OpenTelemetry 在 .NET 微服务中的落地方式以及 Jaeger、SkyWalking、.NET Aspire Dashboard 等可视化后端与消息场景的追踪实践。读完本文你将掌握 Trace/Span 建模、W3C Trace Context 传播、OpenTelemetry 插桩与导出链路并能基于仓库内 Observability 系列文档 构建完整的微服务可观测性方案。一、为什么微服务架构离不开分布式追踪在单体应用中一次请求的调用路径都在同一个进程内借助日志时间戳即可大致还原执行顺序。但在微服务架构下一次用户请求会横跨 API 网关、多个业务服务、数据库、消息队列与第三方依赖任何一个环节变慢或报错都难以通过单机日志定位。分布式追踪正是为了解决这一最棘手的微服务问题而生的技术它为一次端到端请求建立全局唯一的关联标识并记录每个服务内的工作单元及相互之间的调用关系从而把散落在各服务中的执行片段重新串联成一条完整链路。在 Microservices 专题 中可观测性被列为微服务架构的关键能力之一而 Observability 专题 明确指出可观测性由日志Logging、追踪Tracing、指标Monitoring三类信号共同构成。分布式追踪在其中扮演串联者角色与 Correlation ID 的关系CorrelationId 专题 讲解的是用单一请求标识在服务间透传本质是追踪的简化形态分布式追踪在其之上增加了层级化的 Span 结构与耗时数据。与日志的关系追踪的 Trace/Span ID 可写入日志上下文让日志检索与链路查询互相关联。与诊断的关系Diagnostics 专题 覆盖了 .NET 底层的 Activity、DiagnosticSource、EventSource 等机制它们正是 OpenTelemetry .NET 得以实现自动插桩的底层基础。二、分布式追踪的核心概念模型1. Trace 与 Span分布式追踪的基础数据模型由两个层级组成Trace追踪代表一次完整的端到端请求由唯一 Trace ID 标识。Span跨度Trace 内的基本工作单元代表一次具名、计时的操作例如处理 HTTP 请求执行 SQL 查询向 Kafka 发布消息。每个 Span 由 Span ID 标识并携带名称与开始/结束时间戳Attributes属性描述操作的键值对如 HTTP 方法、URL、状态码、消息主题等Events事件Span 生命周期内的时间戳标注如异常堆栈、缓存命中Status状态操作成功或失败的结论父 Span 引用构成一棵树状结构。从源码结构看Diagnostics 专题 所引用的System.Diagnostics.Activity、ActivitySource、ActivityListener、ActivityLink等类型正是 .NET 对 Span 概念的本地实现而 OpenTelemetry .NET SDK 则负责把 Activity 桥接为 OpenTelemetry 的 Span 并导出。2. Context Propagation上下文传播单个服务内的 Span 容易生成难点在于跨进程传播上下文服务 A 调用服务 B 时必须把 Trace ID 与父 Span ID 透传给 BB 才能把自己的 Span 挂到同一条链路上。这一机制称为 Context Propagation。W3C Trace Context 标准是当前事实上的传播格式主要通过两个 HTTP 头工作traceparent携带version-traceid-spanid-flags四段信息例如00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01tracestate携带供应商自定义的附加追踪状态键值对列表。除追踪上下文外Baggage用于沿调用链传播业务键值对如用户 ID、租户 ID它不参与追踪树构建但可供各服务的 Span 读取并作为高基数属性写入从而提升追踪数据的可查询维度。相关指南如 Jimmy Bogard 的Increasing Trace Cardinality with Activity Tags and Baggage专门讨论了如何用 Activity Tags 与 Baggage 提高追踪基数。3. 语义约定Semantic Conventions为了让来自不同语言、不同框架的 Span 具有一致的可读性OpenTelemetry 定义了跨领域的语义约定即对 Span 属性键名与取值进行标准化。专题文档重点覆盖了三类HTTP Span 语义约定统一http.method、http.url、http.status_code、http.route等属性RPC Span 语义约定统一rpc.system、rpc.service、rpc.method等属性适用于 gRPC 等 RPC 场景可参考仓库 gRPC 专题Messaging 语义约定统一消息生产者/消费者场景的属性如messaging.system、messaging.destination、messaging.message_id等是 消息驱动架构 与 Messaging 专题 下追踪落地的关键规范。遵循语义约定是保证追踪数据能被 Jaeger、Grafana Tempo、SkyWalking 等后端正确聚合与检索的前提。三、OpenTelemetry统一的三信号观测标准OpenTelemetry 是 CNCF 孵化的可观测性标准目标是为 Traces、Metrics、Logs 三类信号提供统一的 API、SDK 与数据协议。其架构自上而下分为四层专题文档中引用的The Big Pieces系列文章对每一层都有深入剖析层次职责说明API定义 TracerProvider、Tracer、Span、Meter、Logger 等抽象接口应用只依赖 API 编程不绑定具体实现SDK实现 API负责采样、Span 处理器、批处理与导出通过配置控制数据生成与流向Instrumentation自动插桩库与手动插桩自动捕获 HTTP、DB、gRPC、Redis 等常见调用Exporters / Collector把遥测数据发送到后端支持 OTLP、Jaeger、Prometheus 等协议其中OTLPOpenTelemetry Protocol是官方原生协议支持 gRPC 与 HTTP 两种传输方式已发布 1.0 规范并被 Jaeger 原生支持OpenTelemetry Collector则是一个独立进程负责接收Receivers、处理Processors如批量、采样、属性修改、转发Exporters遥测数据起到解耦应用与后端的管道作用其 contrib 仓库还提供了大量扩展组件与演示配置。专题文档中提及的资源清单如Awesome OpenTelemetry精选列表、semantic-conventions仓库可视为围绕这套标准的延伸学习索引在仓库内Aspire 专题 也大量涉及 OpenTelemetry 数据在本地开发中的可视化可作为配套参考。四、在 .NET 微服务中落地 OpenTelemetry 追踪专题文档的重心明显偏向 .NET 生态从 .NET Core 3.0 引入的 Activity API 改进到 OpenTelemetry .NET 1.0 发布再到 .NET 8 时代的 Aspire 集成构成了完整的落地路径。1. 底层基础System.Diagnostics.NET 的追踪能力并非 OpenTelemetry 独有而是建立在 BCL 的System.Diagnostics之上Activity / ActivitySource.NET 5 引入的追踪原语ActivitySource.StartActivity()创建 SpanActivityListener监听并消费DiagnosticSource进程内的高性能事件发布/订阅机制ASP.NET Core、HttpClient、EF Core 等都通过它发出诊断事件EventSource / EventListener面向 ETW 与跨平台事件的低开销跟踪设施适合运行时级别的诊断。OpenTelemetry .NET SDK 的工作方式可以概括为订阅这些诊断源 将 Activity 桥接为 OTel Span这也是它能实现近乎零侵入自动插桩的根本原因。专题文档中关于 Activity API 可用性改进的设计文档Part 1 / Part 2记录了这一演进的来龙去脉。2. 自动插桩Instrumentation 库在 ASP.NET Core 应用中启用追踪的典型配置模式如下基于 OpenTelemetry .NET 常见用法各包版本以官方 NuGet 为准using OpenTelemetry.Trace; builder.Services.AddOpenTelemetry() .WithTracing(tracing { tracing .AddSource(MyApp.*) // 监听自定义 ActivitySource .AddAspNetCoreInstrumentation() // 自动捕获入站 HTTP 请求 .AddHttpClientInstrumentation() // 自动捕获出站 HTTP 调用 .AddSqlClientInstrumentation() // 自动捕获 SQL Server 调用 .AddGrpcClientInstrumentation() // 自动捕获 gRPC 出站调用 .AddOtlpExporter(); // 通过 OTLP 导出gRPC/HTTP });专题文档重点列举了以下 .NET 插桩/扩展组件它们分别对应不同的依赖类型OpenTelemetry.Instrumentation.AspNetCore入站 HTTP 请求自动追踪OpenTelemetry.Instrumentation.HttpHttpClient 出站调用自动追踪OpenTelemetry.Instrumentation.SqlClient数据库调用追踪OpenTelemetry.Instrumentation.GrpcNetClientgRPC 客户端调用追踪与 gRPC 专题 配套OpenTelemetry.Instrumentation.StackExchangeRedisRedis 缓存调用追踪MongoDB.Driver.Core.Extensions.DiagnosticSources让 MongoDB 驱动通过System.Diagnostics暴露遥测数据OpenTelemetry.Exporter.InMemory把数据写入内存缓冲常用于单元测试与演示。从 Diagnostics 专题 可见.NET 运行时与 ASP.NET Core 自身的诊断源如HostingApplicationDiagnostics、DiagnosticsHandler是这些插桩库的数据来源理解这一调用链有助于排查为什么没有 Span之类的疑难问题。3. 手动插桩为业务方法创建 Span自动插桩覆盖的是框架级调用业务级的关键路径如计算订单总额调用第三方风控通常需要手动插桩。典型模式是创建自定义ActivitySource并显式开启 Activitypublic class OrderService { private static readonly ActivitySource Source new(OrderService, 1.0.0); public async TaskOrder PlaceOrderAsync(OrderRequest request, CancellationToken ct) { using var activity Source.StartActivity(OrderService.PlaceOrder); activity?.SetTag(order.customerId, request.CustomerId); // 业务属性 activity?.SetTag(order.items, request.Items.Count); try { // 业务逻辑... activity?.SetStatus(ActivityStatusCode.Ok); return order; } catch (Exception ex) { activity?.SetStatus(ActivityStatusCode.Error, ex.Message); activity?.RecordException(ex); // 记录异常事件 throw; } } }只要在WithTracing中通过AddSource(OrderService)订阅该源这些手动 Span 就会与框架自动 Span 合并为同一条链路。专题文档推荐的Manual Instrumentation、Extending/Customizing the SDK等资料正是这一环节的深入材料。4. 常见坑与进阶话题专题文档还收录了大量实战排错经验值得留意Where are my traces?无 Span 生成时需依次检查 Instrumentation 是否注册、AddSource是否匹配自定义源、采样器是否丢弃、导出器与后端地址是否连通公开 API 端点的追踪策略对公网入口可选择性关闭传播或调整采样避免敏感链路信息外泄与高基数开销单元测试插桩借助 InMemory Exporter 与 Aspire Dashboard可以在测试与本地开发阶段直接可视化 Span。五、可视化与后端Jaeger、SkyWalking、Aspire Dashboard追踪数据需要后端存储与 UI 才能发挥作用专题文档涉及三类典型方案1. JaegerJaeger 是最流行的开源追踪后端专题文档收录了从 OpenTracing C# 客户端、Jaeger .NET 客户端到ASP.NET Core Jaeger Tye全流程系列文章。值得注意的是Jaeger 现已原生支持 OTLP不再强制要求 Jaeger 专有协议——这意味着 OpenTelemetry .NET 应用可以直接通过 OTLP 把数据送入 Jaeger配置链路显著简化。2. Apache SkyWalkingSkyWalking 是另一个完整的 APM 方案.NET 侧对应SkyAPM-dotnet探针SkyApm.Diagnostics.AspNetCore 等。专题文档中的多篇文章展示了如何在微服务框架中接入 SkyWalking 实现分布式链路追踪适合已选型 SkyWalking 的团队。3. .NET Aspire Dashboard对于 .NET 开发者的本地开发场景Aspire 专题 中重点收录的.NET Aspire Dashboard可直接消费 OpenTelemetry 数据在浏览器中查看 Trace 瀑布图、结构化日志与指标无需部署外部后端是本地验证追踪链路的高性价比工具其独立模式Standalone Dashboard也支持附加到既有应用。Aspire 本身即被定位为可观测的、面向生产的分布式应用栈与 OpenTelemetry 深度集成。此外Grafana 生态Tempo 存追踪、Loki 存日志、Prometheus 存指标与 OpenTelemetry Collector 组合是另一条常见的生产级观测链路仓库内 LoggingLoki 方向与 MonitoringPrometheus/Grafana 方向两篇专题可与之互补。六、消息驱动的分布式追踪MassTransit、NServiceBus 与消息语义在 事件驱动架构 与异步消息场景中追踪上下文不再经由 HTTP 头传播而是随消息本身透传写入消息头这正是 OpenTelemetry Messaging 语义约定所要标准化的内容。专题文档为此提供了专门资源MassTransit v8原生支持 OpenTelemetry可自动为消费者/生产者创建 Span 并沿消息传播上下文仓库 MassTransit 专题 有框架总览NServiceBus.Extensions.Diagnostics.OpenTelemetry为 NServiceBus 提供诊断桥接相关示例项目如distributed-tracing-for-messaging演示了基于 RabbitMQ 的追踪链路仓库 Messaging 专题 及其下的 Kafka、RabbitMQ、NATS 文档可作为消息中间件选型参考。在消息链路中需要注意消息的消费可能异步延迟发生生产者与消费者的 Span 之间通常通过Span Link而非父子关系关联以保证 Trace 树仍以入站请求为根。七、学习路线与可运行示例专题文档最后给出了一组高质量示例与学习资源按其主线可组织为如下学习路径概念入门先读 OpenTelemetry 官方What is OpenTelemetry?与规范总览建立 API/SDK/信号的整体认知再看The Big Pieces系列Specification、Context Propagation、Client 架构、Collector 架构理解各组件边界。.NET 快速上手从5 Minutes Getting Started与官方 Getting Startedinstrumentation/net开始跑通应用 → SDK → 控制台/Jaeger 导出的最小闭环随后学习自动插桩库与手动插桩。对照可运行示例OpenTelemetry Astronomy Shopopentelemetry-demo官方微服务演示应用覆盖 Web、消息、DB、网关等多类依赖最适合整体观摩OtlpDemo / practical-opentelemetry聚焦 OTLP 多协议HTTP/gRPC/UDP/TCP导出与 .NET 实践opentelemetry-tracing-demo / ExploringDistributedTracingWithAspNet多服务串联的追踪演示practical-net-otelcollector结合 OpenTelemetry Collector 的 .NET 可观测性实操grafana-otel-dotnetASP.NET Core Prometheus Loki Grafana Collector 的完整组合示例。深入定制学习 Extending / Customizing OpenTelemetry .NET SDK掌握采样器、Span 处理器、资源属性等扩展点使用 InMemory Exporter 在单元测试中验证追踪行为。八、总结分布式追踪把微服务从一堆难以关联的日志变成一棵可查询的调用树而 OpenTelemetry 通过统一的 API、SDK、语义约定与 OTLP 协议让 .NET 开发者可以用一套代码接入 Jaeger、SkyWalking、Grafana、Aspire Dashboard 等任意后端。落地时建议遵循先基于System.Diagnostics与自动插桩库覆盖框架调用再对业务关键路径手动插桩按语义约定补充属性最后通过 Collector 统一收口并接入可视化后端。如需继续深入可在本仓库中按以下路径展开阅读Observability 总览 → Distributed Tracing → Diagnostics底层机制→ CorrelationId简化关联方案→ Logging 与 Monitoring其余两类信号→ Aspire本地可视化→ MassTransit 与 Messaging消息链路追踪。【免费下载链接】awesome-software-architecture A curated list of awesome articles, videos, and other resources to learn and practice software architecture, patterns, and principles.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-software-architecture创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
分布式追踪与 OpenTelemetry 实战指南：为 .NET 微服务构建端到端可观测性
分布式追踪与 OpenTelemetry 实战指南为 .NET 微服务构建端到端可观测性【免费下载链接】awesome-software-architecture A curated list of awesome articles, videos, and other resources to learn and practice software architecture, patterns, and principles.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-software-architecture本篇技术指南以开源仓库 awesome-software-architecture 中 分布式追踪专题文档 为核心骨架系统讲解分布式追踪Distributed Tracing与 OpenTelemetry 的核心概念、上下文传播机制、语义约定、OpenTelemetry 在 .NET 微服务中的落地方式以及 Jaeger、SkyWalking、.NET Aspire Dashboard 等可视化后端与消息场景的追踪实践。读完本文你将掌握 Trace/Span 建模、W3C Trace Context 传播、OpenTelemetry 插桩与导出链路并能基于仓库内 Observability 系列文档 构建完整的微服务可观测性方案。一、为什么微服务架构离不开分布式追踪在单体应用中一次请求的调用路径都在同一个进程内借助日志时间戳即可大致还原执行顺序。但在微服务架构下一次用户请求会横跨 API 网关、多个业务服务、数据库、消息队列与第三方依赖任何一个环节变慢或报错都难以通过单机日志定位。分布式追踪正是为了解决这一最棘手的微服务问题而生的技术它为一次端到端请求建立全局唯一的关联标识并记录每个服务内的工作单元及相互之间的调用关系从而把散落在各服务中的执行片段重新串联成一条完整链路。在 Microservices 专题 中可观测性被列为微服务架构的关键能力之一而 Observability 专题 明确指出可观测性由日志Logging、追踪Tracing、指标Monitoring三类信号共同构成。分布式追踪在其中扮演串联者角色与 Correlation ID 的关系CorrelationId 专题 讲解的是用单一请求标识在服务间透传本质是追踪的简化形态分布式追踪在其之上增加了层级化的 Span 结构与耗时数据。与日志的关系追踪的 Trace/Span ID 可写入日志上下文让日志检索与链路查询互相关联。与诊断的关系Diagnostics 专题 覆盖了 .NET 底层的 Activity、DiagnosticSource、EventSource 等机制它们正是 OpenTelemetry .NET 得以实现自动插桩的底层基础。二、分布式追踪的核心概念模型1. Trace 与 Span分布式追踪的基础数据模型由两个层级组成Trace追踪代表一次完整的端到端请求由唯一 Trace ID 标识。Span跨度Trace 内的基本工作单元代表一次具名、计时的操作例如处理 HTTP 请求执行 SQL 查询向 Kafka 发布消息。每个 Span 由 Span ID 标识并携带名称与开始/结束时间戳Attributes属性描述操作的键值对如 HTTP 方法、URL、状态码、消息主题等Events事件Span 生命周期内的时间戳标注如异常堆栈、缓存命中Status状态操作成功或失败的结论父 Span 引用构成一棵树状结构。从源码结构看Diagnostics 专题 所引用的System.Diagnostics.Activity、ActivitySource、ActivityListener、ActivityLink等类型正是 .NET 对 Span 概念的本地实现而 OpenTelemetry .NET SDK 则负责把 Activity 桥接为 OpenTelemetry 的 Span 并导出。2. Context Propagation上下文传播单个服务内的 Span 容易生成难点在于跨进程传播上下文服务 A 调用服务 B 时必须把 Trace ID 与父 Span ID 透传给 BB 才能把自己的 Span 挂到同一条链路上。这一机制称为 Context Propagation。W3C Trace Context 标准是当前事实上的传播格式主要通过两个 HTTP 头工作traceparent携带version-traceid-spanid-flags四段信息例如00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01tracestate携带供应商自定义的附加追踪状态键值对列表。除追踪上下文外Baggage用于沿调用链传播业务键值对如用户 ID、租户 ID它不参与追踪树构建但可供各服务的 Span 读取并作为高基数属性写入从而提升追踪数据的可查询维度。相关指南如 Jimmy Bogard 的Increasing Trace Cardinality with Activity Tags and Baggage专门讨论了如何用 Activity Tags 与 Baggage 提高追踪基数。3. 语义约定Semantic Conventions为了让来自不同语言、不同框架的 Span 具有一致的可读性OpenTelemetry 定义了跨领域的语义约定即对 Span 属性键名与取值进行标准化。专题文档重点覆盖了三类HTTP Span 语义约定统一http.method、http.url、http.status_code、http.route等属性RPC Span 语义约定统一rpc.system、rpc.service、rpc.method等属性适用于 gRPC 等 RPC 场景可参考仓库 gRPC 专题Messaging 语义约定统一消息生产者/消费者场景的属性如messaging.system、messaging.destination、messaging.message_id等是 消息驱动架构 与 Messaging 专题 下追踪落地的关键规范。遵循语义约定是保证追踪数据能被 Jaeger、Grafana Tempo、SkyWalking 等后端正确聚合与检索的前提。三、OpenTelemetry统一的三信号观测标准OpenTelemetry 是 CNCF 孵化的可观测性标准目标是为 Traces、Metrics、Logs 三类信号提供统一的 API、SDK 与数据协议。其架构自上而下分为四层专题文档中引用的The Big Pieces系列文章对每一层都有深入剖析层次职责说明API定义 TracerProvider、Tracer、Span、Meter、Logger 等抽象接口应用只依赖 API 编程不绑定具体实现SDK实现 API负责采样、Span 处理器、批处理与导出通过配置控制数据生成与流向Instrumentation自动插桩库与手动插桩自动捕获 HTTP、DB、gRPC、Redis 等常见调用Exporters / Collector把遥测数据发送到后端支持 OTLP、Jaeger、Prometheus 等协议其中OTLPOpenTelemetry Protocol是官方原生协议支持 gRPC 与 HTTP 两种传输方式已发布 1.0 规范并被 Jaeger 原生支持OpenTelemetry Collector则是一个独立进程负责接收Receivers、处理Processors如批量、采样、属性修改、转发Exporters遥测数据起到解耦应用与后端的管道作用其 contrib 仓库还提供了大量扩展组件与演示配置。专题文档中提及的资源清单如Awesome OpenTelemetry精选列表、semantic-conventions仓库可视为围绕这套标准的延伸学习索引在仓库内Aspire 专题 也大量涉及 OpenTelemetry 数据在本地开发中的可视化可作为配套参考。四、在 .NET 微服务中落地 OpenTelemetry 追踪专题文档的重心明显偏向 .NET 生态从 .NET Core 3.0 引入的 Activity API 改进到 OpenTelemetry .NET 1.0 发布再到 .NET 8 时代的 Aspire 集成构成了完整的落地路径。1. 底层基础System.Diagnostics.NET 的追踪能力并非 OpenTelemetry 独有而是建立在 BCL 的System.Diagnostics之上Activity / ActivitySource.NET 5 引入的追踪原语ActivitySource.StartActivity()创建 SpanActivityListener监听并消费DiagnosticSource进程内的高性能事件发布/订阅机制ASP.NET Core、HttpClient、EF Core 等都通过它发出诊断事件EventSource / EventListener面向 ETW 与跨平台事件的低开销跟踪设施适合运行时级别的诊断。OpenTelemetry .NET SDK 的工作方式可以概括为订阅这些诊断源 将 Activity 桥接为 OTel Span这也是它能实现近乎零侵入自动插桩的根本原因。专题文档中关于 Activity API 可用性改进的设计文档Part 1 / Part 2记录了这一演进的来龙去脉。2. 自动插桩Instrumentation 库在 ASP.NET Core 应用中启用追踪的典型配置模式如下基于 OpenTelemetry .NET 常见用法各包版本以官方 NuGet 为准using OpenTelemetry.Trace; builder.Services.AddOpenTelemetry() .WithTracing(tracing { tracing .AddSource(MyApp.*) // 监听自定义 ActivitySource .AddAspNetCoreInstrumentation() // 自动捕获入站 HTTP 请求 .AddHttpClientInstrumentation() // 自动捕获出站 HTTP 调用 .AddSqlClientInstrumentation() // 自动捕获 SQL Server 调用 .AddGrpcClientInstrumentation() // 自动捕获 gRPC 出站调用 .AddOtlpExporter(); // 通过 OTLP 导出gRPC/HTTP });专题文档重点列举了以下 .NET 插桩/扩展组件它们分别对应不同的依赖类型OpenTelemetry.Instrumentation.AspNetCore入站 HTTP 请求自动追踪OpenTelemetry.Instrumentation.HttpHttpClient 出站调用自动追踪OpenTelemetry.Instrumentation.SqlClient数据库调用追踪OpenTelemetry.Instrumentation.GrpcNetClientgRPC 客户端调用追踪与 gRPC 专题 配套OpenTelemetry.Instrumentation.StackExchangeRedisRedis 缓存调用追踪MongoDB.Driver.Core.Extensions.DiagnosticSources让 MongoDB 驱动通过System.Diagnostics暴露遥测数据OpenTelemetry.Exporter.InMemory把数据写入内存缓冲常用于单元测试与演示。从 Diagnostics 专题 可见.NET 运行时与 ASP.NET Core 自身的诊断源如HostingApplicationDiagnostics、DiagnosticsHandler是这些插桩库的数据来源理解这一调用链有助于排查为什么没有 Span之类的疑难问题。3. 手动插桩为业务方法创建 Span自动插桩覆盖的是框架级调用业务级的关键路径如计算订单总额调用第三方风控通常需要手动插桩。典型模式是创建自定义ActivitySource并显式开启 Activitypublic class OrderService { private static readonly ActivitySource Source new(OrderService, 1.0.0); public async TaskOrder PlaceOrderAsync(OrderRequest request, CancellationToken ct) { using var activity Source.StartActivity(OrderService.PlaceOrder); activity?.SetTag(order.customerId, request.CustomerId); // 业务属性 activity?.SetTag(order.items, request.Items.Count); try { // 业务逻辑... activity?.SetStatus(ActivityStatusCode.Ok); return order; } catch (Exception ex) { activity?.SetStatus(ActivityStatusCode.Error, ex.Message); activity?.RecordException(ex); // 记录异常事件 throw; } } }只要在WithTracing中通过AddSource(OrderService)订阅该源这些手动 Span 就会与框架自动 Span 合并为同一条链路。专题文档推荐的Manual Instrumentation、Extending/Customizing the SDK等资料正是这一环节的深入材料。4. 常见坑与进阶话题专题文档还收录了大量实战排错经验值得留意Where are my traces?无 Span 生成时需依次检查 Instrumentation 是否注册、AddSource是否匹配自定义源、采样器是否丢弃、导出器与后端地址是否连通公开 API 端点的追踪策略对公网入口可选择性关闭传播或调整采样避免敏感链路信息外泄与高基数开销单元测试插桩借助 InMemory Exporter 与 Aspire Dashboard可以在测试与本地开发阶段直接可视化 Span。五、可视化与后端Jaeger、SkyWalking、Aspire Dashboard追踪数据需要后端存储与 UI 才能发挥作用专题文档涉及三类典型方案1. JaegerJaeger 是最流行的开源追踪后端专题文档收录了从 OpenTracing C# 客户端、Jaeger .NET 客户端到ASP.NET Core Jaeger Tye全流程系列文章。值得注意的是Jaeger 现已原生支持 OTLP不再强制要求 Jaeger 专有协议——这意味着 OpenTelemetry .NET 应用可以直接通过 OTLP 把数据送入 Jaeger配置链路显著简化。2. Apache SkyWalkingSkyWalking 是另一个完整的 APM 方案.NET 侧对应SkyAPM-dotnet探针SkyApm.Diagnostics.AspNetCore 等。专题文档中的多篇文章展示了如何在微服务框架中接入 SkyWalking 实现分布式链路追踪适合已选型 SkyWalking 的团队。3. .NET Aspire Dashboard对于 .NET 开发者的本地开发场景Aspire 专题 中重点收录的.NET Aspire Dashboard可直接消费 OpenTelemetry 数据在浏览器中查看 Trace 瀑布图、结构化日志与指标无需部署外部后端是本地验证追踪链路的高性价比工具其独立模式Standalone Dashboard也支持附加到既有应用。Aspire 本身即被定位为可观测的、面向生产的分布式应用栈与 OpenTelemetry 深度集成。此外Grafana 生态Tempo 存追踪、Loki 存日志、Prometheus 存指标与 OpenTelemetry Collector 组合是另一条常见的生产级观测链路仓库内 LoggingLoki 方向与 MonitoringPrometheus/Grafana 方向两篇专题可与之互补。六、消息驱动的分布式追踪MassTransit、NServiceBus 与消息语义在 事件驱动架构 与异步消息场景中追踪上下文不再经由 HTTP 头传播而是随消息本身透传写入消息头这正是 OpenTelemetry Messaging 语义约定所要标准化的内容。专题文档为此提供了专门资源MassTransit v8原生支持 OpenTelemetry可自动为消费者/生产者创建 Span 并沿消息传播上下文仓库 MassTransit 专题 有框架总览NServiceBus.Extensions.Diagnostics.OpenTelemetry为 NServiceBus 提供诊断桥接相关示例项目如distributed-tracing-for-messaging演示了基于 RabbitMQ 的追踪链路仓库 Messaging 专题 及其下的 Kafka、RabbitMQ、NATS 文档可作为消息中间件选型参考。在消息链路中需要注意消息的消费可能异步延迟发生生产者与消费者的 Span 之间通常通过Span Link而非父子关系关联以保证 Trace 树仍以入站请求为根。七、学习路线与可运行示例专题文档最后给出了一组高质量示例与学习资源按其主线可组织为如下学习路径概念入门先读 OpenTelemetry 官方What is OpenTelemetry?与规范总览建立 API/SDK/信号的整体认知再看The Big Pieces系列Specification、Context Propagation、Client 架构、Collector 架构理解各组件边界。.NET 快速上手从5 Minutes Getting Started与官方 Getting Startedinstrumentation/net开始跑通应用 → SDK → 控制台/Jaeger 导出的最小闭环随后学习自动插桩库与手动插桩。对照可运行示例OpenTelemetry Astronomy Shopopentelemetry-demo官方微服务演示应用覆盖 Web、消息、DB、网关等多类依赖最适合整体观摩OtlpDemo / practical-opentelemetry聚焦 OTLP 多协议HTTP/gRPC/UDP/TCP导出与 .NET 实践opentelemetry-tracing-demo / ExploringDistributedTracingWithAspNet多服务串联的追踪演示practical-net-otelcollector结合 OpenTelemetry Collector 的 .NET 可观测性实操grafana-otel-dotnetASP.NET Core Prometheus Loki Grafana Collector 的完整组合示例。深入定制学习 Extending / Customizing OpenTelemetry .NET SDK掌握采样器、Span 处理器、资源属性等扩展点使用 InMemory Exporter 在单元测试中验证追踪行为。八、总结分布式追踪把微服务从一堆难以关联的日志变成一棵可查询的调用树而 OpenTelemetry 通过统一的 API、SDK、语义约定与 OTLP 协议让 .NET 开发者可以用一套代码接入 Jaeger、SkyWalking、Grafana、Aspire Dashboard 等任意后端。落地时建议遵循先基于System.Diagnostics与自动插桩库覆盖框架调用再对业务关键路径手动插桩按语义约定补充属性最后通过 Collector 统一收口并接入可视化后端。如需继续深入可在本仓库中按以下路径展开阅读Observability 总览 → Distributed Tracing → Diagnostics底层机制→ CorrelationId简化关联方案→ Logging 与 Monitoring其余两类信号→ Aspire本地可视化→ MassTransit 与 Messaging消息链路追踪。【免费下载链接】awesome-software-architecture A curated list of awesome articles, videos, and other resources to learn and practice software architecture, patterns, and principles.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-software-architecture创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考