Hyz.Trace.Client 1.2.2

Hyz.Trace.Client

分布式链路追踪客户端元包（一站式安装），自动引入核心引擎 + HTTP 上报器 + ASP.NET Core 集成 + Prometheus 指标，开箱即用。

目标框架

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

包含的包

安装本元包时自动引入以下依赖：

说明：gRPC 上报器和 ASP.NET Core 集成为内嵌 DLL，仅在 net8.0+ 目标框架下可用；netstandard2.0 目标框架仅包含核心引擎、HTTP 上报和 Prometheus 指标。

快速开始

1. 安装

dotnet add package Hyz.Trace.Client

2. 启动 Dashboard 服务端并获取 API Key

部署 Hyz.Trace.Server（详见其 README），在应用管理页面创建应用获取 API Key（格式：trk_xxxxxxxxxxxxxxxx）。

3. 配置服务

using Hyz.Trace;
using Hyz.Trace.AspNet;

var builder = WebApplication.CreateBuilder(args);

// 链式配置：一行完成追踪 + 上报器注册
builder.AddTrace(options =>
{
    options.Enabled = true;
    options.SampleRate = 1.0;                            // 全量采样
    options.DashboardServerAddress = "http://localhost:5000"; // Dashboard 地址
    options.DashboardApiKey = "trk_xxxxxxxxxxxxxxxx";    // 应用 API Key（从 Dashboard 获取）
    options.DashboardProtocol = ReportProtocol.Http;     // 上报协议
    options.MaxActiveSpans = 10000;
})
.AddTraceReporting();  // 根据配置的 DashboardProtocol 自动注册对应的上报器

// 注册带追踪的服务（DynamicProxy AOP）
builder.Services.AddTraced<IOrderService, OrderService>(ServiceLifetime.Scoped);

// 注册 HttpClient 并自动注入 traceparent 头
builder.Services.AddHttpClient("ExternalApi")
    .AddTracedHttpClient();

4. 启用中间件

var app = builder.Build();

// 追踪中间件必须放在管道最前面（在路由、认证等之前）
app.UseTrace();

app.MapControllers();
app.Run();

完成！每个 HTTP 请求自动创建 Root Span，方法调用自动嵌套 Span，批量上报到 Dashboard。

场景示例

场景一：远程上报到独立 Dashboard（推荐生产）

builder.AddTrace(options =>
{
    options.DashboardServerAddress = "http://trace-server:5000";
    options.DashboardApiKey = "trk_xxxxxxxxxxxxxxxx";
    options.DashboardProtocol = ReportProtocol.Http;
    options.SampleRate = 0.1;  // 生产环境建议 10% 采样
    options.ReportBatchSize = 200;
    options.ReportBatchIntervalMs = 3000;
})
.AddTraceReporting();

场景二：gRPC 上报（高性能，仅 net8.0+）

builder.AddTrace(options =>
{
    options.DashboardServerAddress = "http://trace-server:5001";  // gRPC 端口
    options.DashboardApiKey = "trk_xxxxxxxxxxxxxxxx";
    options.DashboardProtocol = ReportProtocol.Grpc;
})
.AddTraceReporting();

场景三：进程内模式（开发调试，Dashboard 嵌入应用）

// 需要额外安装存储和 Dashboard 包
// dotnet add package Hyz.Trace.Storage.FreeSql
// dotnet add package Hyz.Trace.Dashboard

builder.Services.UseSqliteStorage("Data Source=traces.db");
builder.Services.AddSingleton<RuntimeConfigStore>();

builder.AddTrace(options =>
{
    options.DashboardProtocol = ReportProtocol.InProcess;
})
.AddTraceReporting();

// ...
app.UseTrace();
app.UseTraceDashboard();  // 启用嵌入式面板

场景四：结合日志

安装对应的日志包（单独安装）：

dotnet add package Hyz.Trace.Logging.Serilog  # 或 Hyz.Trace.Logging.NLog

环境变量

支持通过环境变量配置（无需修改代码）：

重要说明

• 无需配置 ApplicationName：客户端不再需要设置应用名称，应用归属完全由 DashboardApiKey 确定，服务端通过 API Key 的 SHA256 哈希自动绑定应用
• 链式 API：builder.AddTrace(...).AddTraceReporting() 是推荐的配置方式，替代旧版的三段式配置
• 自动路径排除：UseTrace() 中间件自动排除 Dashboard 路径（/trace-dashboard）和健康检查路径，防止递归追踪
• 异步传播：TraceContext 基于 AsyncLocal，async/await、Task.Run、线程池切换时自动传播

扩展包安装

如需额外功能，请单独安装：

# Serilog 日志集成
dotnet add package Hyz.Trace.Logging.Serilog

# NLog 日志集成
dotnet add package Hyz.Trace.Logging.NLog

# 进程内 Dashboard（嵌入式 UI）
dotnet add package Hyz.Trace.Dashboard
dotnet add package Hyz.Trace.Storage.FreeSql  # 或 Hyz.Trace.Storage.ClickHouse

# Fody IL 编织（无接口 AOP）
dotnet add package Hyz.Trace.Weaving.Fody

完整选项参考

详见 Hyz.Trace README 的 TraceOptions 完整列表。