Hyz.Trace 1.4.0

Hyz.Trace

分布式链路追踪核心引擎，提供 TraceContext 上下文传播、TraceScope Span 管理、采样策略、性能熔断、敏感数据脱敏和 AOP 拦截支持。

核心能力

• 上下文传播 — 基于 AsyncLocal<T> 的 TraceContext，随 ExecutionContext 跨 async/await 自动传播
• Span 生命周期管理 — TraceScope 统一创建/结束 Span，支持标签、错误记录与父子关系
• 采样与熔断 — 概率/速率/模式采样器，异常率超阈值自动熔断
• 敏感数据脱敏 — 内置密码、Token、密钥等字段自动脱敏
• AOP 拦截 — DynamicProxy / Fody IL 编织 / Source Generator 三种织入方式
• 双层缓冲上报 — TraceScope 有界 Channel 导出 + 上报器无界缓冲后台刷新
• 丢弃可观测（OnDrop） — 缓冲满丢弃 Span 时触发回调事件，便于日志与监控定位（见「丢弃回调」）
• 优雅停机兜底 — TraceScope.Shutdown() 兜底排空缓冲，避免进程退出丢数据（见「优雅停机兜底」）

目标框架

• netstandard2.0 / net8.0 / net9.0 / net10.0

核心组件

TraceContext — 异步本地上下文

基于 AsyncLocal<T> 实现，随 ExecutionContext 自动跨 async/await 传播。

// 获取当前上下文
var ctx = TraceContext.Current;
string? traceId = TraceContext.TraceId;
string? spanId = TraceContext.SpanId;
bool isSuppressed = TraceContext.IsSuppressed;

// 快照与恢复（线程池/Task.Run 场景）
var snapshot = TraceContext.Capture();
await Task.Run(() => TraceContext.Run(snapshot, () => DoWork()));

// 抑制追踪（健康检查、后台任务等）
using (TraceContext.Suppress())
{
    await BackgroundTaskAsync();
}

TraceScope — Span 生命周期管理

using var scope = TraceScope.Create("OrderService.CreateOrder");
scope.SetTag("orderId", "ORD-12345");
scope.SetTag("customerId", "CUST-001");

try
{
    var order = await _repository.CreateAsync(...);
    scope.SetOk();
    return order;
}
catch (Exception ex)
{
    scope.SetError(ex);
    throw;
}

配置体系（TraceOptions）

支持三级配置优先级：环境变量 > JSON 配置 > 代码配置 > 默认值。

// 通过 ASP.NET Core 链式 API 配置
builder.AddTrace(options =>
{
    // 基础开关
    options.Enabled = true;
    options.SampleRate = 1.0;

    // 性能保护
    options.MaxActiveSpans = 10000;
    options.MaxParameterDepth = 3;
    options.MaxSpanDataLength = 4096;
    options.CircuitBreakerThreshold = 0.1;   // 异常率超过 10% 触发熔断

    // 采样
    options.Sampler = new ProbabilisticSampler(0.5);  // 自定义采样器
    options.MaxSamplesPerSecond = 0;       // 0=不限制

    // 过滤
    options.IncludePatterns = new[] { "Order*", "Payment*" };
    options.ExcludePatterns = new[] { "HealthCheck*" };
    options.ExcludePathPrefixes = new[] { "/health", "/metrics" };
    options.SensitiveParameters = new[] { "password", "token" };

    // 上报配置
    options.DashboardServerAddress = "";      // 空=进程内模式
    options.DashboardApiKey = "";             // API Key（Dashboard 创建应用获取）
    options.DashboardProtocol = ReportProtocol.InProcess; // InProcess/Http/Grpc
    options.ReportBatchSize = 100;
    options.ReportBatchIntervalMs = 2000;
    options.ReportSendTimeoutSeconds = 10;
    options.ReportMaxRetries = 3;
    options.ReportMaxBufferSize = 10000;

    // 诊断日志（排查时开启，生产环境建议关闭）
    options.EnableDiagnosticLogging = false;
});

TraceOptions 完整列表

重要变更：ApplicationName 配置项已移除。应用归属完全由 DashboardApiKey 确定，服务端通过 API Key 自动设置 ApplicationId 和 ApplicationName。

环境变量

所有 TraceOptions 属性均支持环境变量配置，前缀 HYZ_TRACE_，使用下划线代替驼峰命名：

采样器

内置采样器

// 全量采样（默认）
var sampler = AlwaysOnSampler.Instance;

// 概率采样：50%
var sampler = new ProbabilisticSampler(0.5);

// 速率限制：每秒最多 100 个 Trace
var sampler = new RateLimitingSampler(100);

// 模式匹配采样（包含/排除通配符 + 下游采样器）
var sampler = new PatternSampler(
    new ProbabilisticSampler(0.5),
    includePatterns: new[] { "Order*", "Payment*" },
    excludePatterns: new[] { "HealthCheck*" });

自定义采样器

实现 ISampler 接口：

public interface ISampler
{
    bool ShouldSample(string methodName, Dictionary<string, string>? tags);
}

AOP 注册

DynamicProxy（推荐，接口代理）

// 注册单个带追踪的服务
builder.Services.AddTraced<IOrderService, OrderService>(ServiceLifetime.Scoped);

// 扫描程序集中所有标记了 [Trace] 的接口
builder.Services.AddTracedByType(typeof(OrderService).Assembly, ServiceLifetime.Scoped);

Fody IL 编织

安装 Hyz.Trace.Weaving.Fody 包，在任意类/方法上标记 [Trace] 特性：

[Trace]
public Order CreateOrder(string customerId, decimal amount) { ... }

Source Generator

使用 [Trace] 特性 + partial 方法：

public partial class OrderService
{
    [Trace]
    public partial Order CreateOrder(string customerId, decimal amount);
}

ITraceExporter 导出器

public interface ITraceExporter
{
    void Export(ISpanData span);
    Task ExportBatchAsync(IReadOnlyList<ISpanData> spans, CancellationToken ct = default);
}

内置导出器：

• HttpTraceReporter（Hyz.Trace.Reporting.Http）— HTTP JSON 批量上报
• GrpcTraceReporter（Hyz.Trace.Reporting.gRPC）— gRPC Protobuf 流式上报
• DashboardExporter（Hyz.Trace.Dashboard）— 进程内直接写入存储
• CompositeTraceExporter（Hyz.Trace.Storage.Abstractions）— 复合导出器（同时发往多个目标）

所有上报器均实现 ITraceReporter（继承 ITraceExporter），并在 Span 因缓冲满被丢弃时触发 OnDrop 事件（见下文「丢弃回调」）。

丢弃回调（OnDrop）

当 Span 因缓冲达到上限无法入队而被丢弃时（导出通道满 Source="ExportChannel"，或上报器缓冲满 Source="HttpReporter"/"GrpcReporter"），会触发 OnDrop 事件，便于日志与监控定位丢失的数据：

// 全局级别：覆盖所有 reporter 及导出通道的丢弃
TraceScope.OnDrop += info =>
    _logger.Warning("Span dropped: {Source} {Method} {Reason} (buffer={BufferCount})",
        info.Source, info.MethodName, info.Reason, info.BufferCount);

// 单 reporter 级别（仅该上报器的缓冲丢弃）
reporter.OnDrop += info => Console.WriteLine(info.ToString());

TraceDroppedInfo 字段：

提示：TraceScope.DroppedCount 提供累计丢弃计数（仅导出通道侧），可结合 OnDrop 一起用于健康检查与告警。

优雅停机兜底（Shutdown）

进程退出前应调用 TraceScope.Shutdown()，它会关闭导出通道、取消后台消费者，并依次调用每个已注册 reporter 的 FlushAsync 兜底排空，避免缓冲中尚未发送的 Span 随进程退出而丢失：

// 在 Program.cs 中注册进程退出钩子
AppDomain.CurrentDomain.ProcessExit += (_, _) => TraceScope.Shutdown();

// 调整兜底刷新超时（默认 10000ms，超时则放弃等待）
TraceScope.ShutdownFlushTimeoutMs = 10000;
TraceScope.Shutdown();   // 阻塞直至各 reporter 刷新完成或超时

若使用 IHostedService / IHostApplicationLifetime，可在 StopAsync 中调用 TraceScope.Shutdown()。Shutdown 后仍可再次 AddReporter 重建通道（便于测试隔离与优雅重启）。

敏感数据脱敏

自动脱敏的参数名（大小写不敏感）：

• password, pwd, passwd
• token, accesstoken, refreshtoken
• secret, apikey, api_key, privatekey
• creditcard, cardnumber, cvv
• authorization, cookie

可通过 SensitiveParameters 追加自定义字段，或通过 SensitivePatterns 添加正则模式。

依赖包

• Castle.Core — DynamicProxy AOP
• Microsoft.Extensions.DependencyInjection.Abstractions — DI 抽象
• Microsoft.Extensions.Logging.Abstractions — 日志抽象
• Microsoft.Extensions.Options — 配置选项
• Microsoft.Extensions.Http — HttpClient 工厂（上报器使用）
• System.Text.Json — JSON 序列化

扩展包