Hyz.Trace.Storage.FreeSql 1.4.1

Hyz.Trace.Storage.FreeSql

基于 FreeSql ORM 的链路追踪存储实现，支持 SQLite、MySQL、PostgreSQL、SQL Server 四种数据库。

目标框架

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

支持的数据库

快速开始

安装

dotnet add package Hyz.Trace.Storage.FreeSql

注册存储

using Hyz.Trace.Storage.FreeSql;

// SQLite（开发/演示，零配置）
builder.Services.UseSqliteStorage("Data Source=traces.db");

// MySQL（BulkCopy 建议 AllowLoadLocalInfile=true）
// builder.Services.UseMySqlStorage("Server=localhost;Port=3306;Database=hyz_trace;User=root;Password=xxx;CharSet=utf8mb4;AllowLoadLocalInfile=true");

// PostgreSQL
// builder.Services.UsePostgreSqlStorage("Host=localhost;Port=5432;Database=hyz_trace;Username=postgres;Password=xxx");

// SQL Server（兼容 2008 R2+，默认 dbo schema，NVARCHAR 全程 Unicode 安全）
// builder.Services.UseSqlServerStorage("Server=localhost;Database=hyz_trace;User Id=sa;Password=xxx;TrustServerCertificate=True");

需要额外注册 RuntimeConfigStore（Dashboard 中间件依赖）：

builder.Services.AddSingleton<RuntimeConfigStore>();

从 DI 获取仓储

注册后，ITraceRepository、IUserRepository、IApplicationRepository 由容器解析，不要手动 new FreeSql*Repository：

using Hyz.Trace.Storage;

// 构造函数注入（推荐）
public class MyService(
    ITraceRepository traces,
    IUserRepository users,
    IApplicationRepository apps)
{
    // ...
}

// 或从 ServiceProvider 解析
var traces = app.Services.GetRequiredService<ITraceRepository>();

生命周期

• IFreeSql 注册为全局单例，三个仓储共享同一实例
• 首次解析 IFreeSql（或依赖它的仓储）时懒创建连接
• 进程关停时由 DI 容器 Dispose 释放 IFreeSql（单例实现 IDisposable）
• 不要 new FreeSqlTraceRepository(DataType, connectionString) — 该构造已移除
• FreeSqlFactory 供扩展方法与诊断使用；业务与测试代码请通过 Use*Storage 注册，勿用 Factory 直接拼仓储

SQLite 连接字符串：仅使用 Data Source 等 Provider 支持的关键字；勿使用 Max Pool Size / Maximum Pool Size（SqlClient 风格关键字会导致解析失败）。

自动创建的表

启动时 FreeSql 自动创建以下表（AutoCreateStructure）：

applications（应用表，含密钥字段）

注意：旧版 report_keys 表已移除，密钥字段合并到 applications 表。

trace_spans（Span 数据表，按月分表 trace_spans_YYYYMM）

索引：idx_{table}_traceid、idx_{table}_appid_time、idx_{table}_app_time、idx_{table}_time

分表说明：Span 数据按月自动分表（trace_spans_YYYYMM），写入按 StartTimeUtc 路由，查询跨表 UNION ALL 合并，过期数据按整表 DROP 清理。启动时自动检测老表 trace_spans 并迁移到分表。

users（用户表）

扩展方法

SQL Server 特定说明

• 版本兼容：支持 SQL Server 2008 R2 及以上版本，时间分桶使用 DATEDIFF+DATEADD+CONVERT 实现，不依赖 2012+ 的 FORMAT 函数
• 字符类型：所有字符串列使用 NVARCHAR(n) Unicode 类型，完美支持中文、日文、emoji 等多语言字符
• 时间类型：DATETIME2(7) 精度 100 纳秒，符合 .NET DateTime 精度
• 标识符：使用 [方括号] 引用，避免关键字冲突
• 建表方式：使用 sys.objects/sys.indexes 做存在性检查（兼容 2008 R2，无 CREATE TABLE IF NOT EXISTS 语法）
• Schema：默认使用 dbo schema
• 表重命名：使用 sp_rename 系统存储过程

依赖包

• Hyz.Trace.Storage.Abstractions — 存储抽象层（依赖）
• FreeSql / FreeSql.Provider.SqliteCore / FreeSql.Provider.MySqlConnector / FreeSql.Provider.PostgreSQL / FreeSql.Provider.SqlServer — ORM 和数据库驱动
• Hyz.Trace.IdGenerator — 雪花 ID 生成器

批量写入

InsertBatchAsync 按批大小自动路由：小批（≤ StagingBatchThreshold，默认 2000 行）走手写分方言 IGNORE（SQLite INSERT OR IGNORE / MySQL INSERT IGNORE / PG ON CONFLICT DO NOTHING），单次往返、零额外查询；大批量（> 阈值）自动路由到 dialect-native 临时表旁路（各方言原生临时表 + 专有 bulk 灌入 + INSERT...SELECT WHERE NOT EXISTS 去重），以获得协议级批量吞吐。SQL Server 始终走 SqlBulkCopy + 唯一索引 IGNORE_DUP_KEY（服务端等价去重，不进临时表）。幂等去重由分表唯一索引 (ApplicationId, TraceId, SpanId) 保证，at-least-once 重复上报不会重复入库。MySQL 的 MySqlBulkCopy 灌入路径由 FreeSqlStorageOptions.EnableMySqlBulkCopy 控制（默认 false，需经真实实例验证唯一键冲突可忽略后再启用）。

性能建议

1. SQLite 适合开发环境或 Span 量小于 100 万/天的小型部署；连接字符串使用 Data Source=... 即可，勿添加 Max Pool Size
2. MySQL 建议对 start_time_utc 和 trace_id 列建立复合索引以提升查询性能，推荐 utf8mb4 字符集
3. PostgreSQL 在高并发场景下性能最佳，建议使用连接池（Maximum Pool Size=50）
4. SQL Server 建议开启连接池（Max Pool Size=100），生产环境推荐使用 SQL Server 2019+ 以获得更好的查询优化器支持；Always On 可用性组环境下在连接字符串中加入 MultiSubnetFailover=True
5. 自动清理任务（Cleanup）默认每天凌晨 2 点执行，根据 DataRetentionDays 配置清理过期数据
6. 对于大规模部署（Span 量 > 1000 万/天），建议使用 Hyz.Trace.Storage.ClickHouse