.NET 内置分布式追踪活动详解

.NET 内置分布式追踪活动详解

docs This repository contains .NET Documentation. 项目地址: https://gitcode.com/gh_mirrors/docs2/docs

什么是分布式追踪活动

分布式追踪是现代微服务架构中重要的诊断工具，它通过记录请求在分布式系统中的流转路径，帮助开发者理解系统行为、诊断性能问题。在.NET生态中，System.Diagnostics.Activity类是实现分布式追踪的核心组件，它代表了一个逻辑操作单元及其上下文信息。

.NET内置的追踪活动类型

.NET运行时和核心库内置了多种追踪活动类型，主要分布在网络通信领域。这些活动遵循OpenTelemetry等业界标准规范，能够与主流APM工具无缝集成。

HTTP客户端请求活动

这是最常见的追踪活动类型，由HttpClient发起HTTP请求时自动生成。

关键特征：

• 活动名称：System.Net.Http.HttpRequestOut
• 显示名称：HTTP方法名（如GET、POST）
• 生命周期：从请求开始到接收响应头结束（不包括读取响应体时间）

重要属性说明：

• http.request.method：标准化的HTTP方法名，非标准方法会标记为_OTHER
• url.full：完整请求URL（默认会隐藏查询参数保护隐私）
• error.type：请求失败时会记录具体错误类型
• http.response.status_code：响应状态码（仅当收到响应时）

版本注意：

• .NET 9+版本提供了完整的属性支持
• 早期版本建议配合OpenTelemetry.Instrumentation.Http包使用

连接等待活动（实验性）

当HTTP请求需要等待连接池中的可用连接时产生。

典型场景：

• 连接池耗尽时新请求排队
• 高并发下的连接等待情况

技术细节：

• 活动名称：Experimental.System.Net.Http.Connections.WaitForConnection
• 显示名称格式：HTTP wait_for_connection {address}:{port}
• 与父请求活动形成父子关系

连接建立活动（实验性）

描述HTTP底层连接的建立过程，包括：

• DNS解析
• TCP连接建立
• TLS握手

关键特点：

• 总是作为根活动独立存在
• 成功后会与使用该连接的HTTP请求活动建立链接关系
• 显示名称格式：HTTP connection_setup {address}:{port}

DNS查询活动（实验性）

记录通过System.Net.Dns进行的域名解析操作。

属性说明：

• dns.question.name：查询的域名或IP
• dns.answers：解析结果数组
• 错误时会记录具体的SocketError代码

Socket连接活动（实验性）

记录底层Socket连接建立过程，支持：

• TCP/UDP连接
• Unix域套接字

网络层信息：

• network.transport：传输层协议(tcp/udp/unix)
• network.type：网络层协议(ipv4/ipv6)
• network.peer.address：对端地址

TLS握手活动（实验性）

记录SSL/TLS握手过程，包含：

• 协议版本协商
• 证书验证
• 密钥交换

关键属性：

• tls.protocol.version：协商的TLS版本(如1.2/1.3)
• server.address：SNI服务器名称(客户端模式)

最佳实践建议

1. 版本适配：实验性功能可能在后续版本调整，生产环境使用时需评估稳定性

2. 性能考量：高频操作的活动采集可能产生开销，建议：

   • 采样策略控制采集量
   • 避免在热点路径上记录过多属性

3. 错误诊断：结合error.type属性可以快速定位网络层问题：

   • DNS解析失败
   • 连接拒绝
   • TLS证书问题

4. 可视化分析：利用活动间的父子/链接关系，可以构建完整的请求流程图，特别有助于：

   • 识别性能瓶颈
   • 分析跨服务调用链
   • 调试连接池问题

总结

.NET内置的分布式追踪活动提供了从应用层到底层网络的全栈可见性，特别是.NET 9+版本增强了网络栈的观测能力。开发者可以利用这些活动数据构建强大的诊断工具，有效提升分布式系统的可观测性水平。

docs This repository contains .NET Documentation. 项目地址: https://gitcode.com/gh_mirrors/docs2/docs