Hyz.Trace 1.0.0

Hyz.Trace

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

目标框架

• 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;
});

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）— 复合导出器（同时发往多个目标）

敏感数据脱敏

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

• 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 序列化

扩展包