Hyz.Trace.Storage.FreeSql 1.0.0

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. 
dotnet add package Hyz.Trace.Storage.FreeSql --version 1.0.0
                    


                    

                
NuGet\Install-Package Hyz.Trace.Storage.FreeSql -Version 1.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Hyz.Trace.Storage.FreeSql" Version="1.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Hyz.Trace.Storage.FreeSql" Version="1.0.0" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Hyz.Trace.Storage.FreeSql" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Hyz.Trace.Storage.FreeSql --version 1.0.0
                    


                    

                
#r "nuget: Hyz.Trace.Storage.FreeSql, 1.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Hyz.Trace.Storage.FreeSql@1.0.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Hyz.Trace.Storage.FreeSql&version=1.0.0
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Hyz.Trace.Storage.FreeSql&version=1.0.0
                    


                            Install as a Cake Tool

Hyz.Trace.Storage.FreeSql

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

目标框架

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

支持的数据库

数据库 适用场景 连接字符串示例
SQLite 开发/小型部署 Data Source=traces.db
MySQL 中小规模生产 Data Source=localhost;Port=3306;Database=hyz_trace;User=root;Password=xxx;CharSet=utf8mb4
PostgreSQL 中大规模生产 Host=localhost;Port=5432;Database=hyz_trace;Username=postgres;Password=xxx

快速开始

安装

dotnet add package Hyz.Trace.Storage.FreeSql

注册存储

using Hyz.Trace.Storage;

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

// MySQL
// builder.Services.UseMySqlStorage("Server=localhost;Port=3306;Database=hyz_trace;User=root;Password=xxx;CharSet=utf8mb4");

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

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

builder.Services.AddSingleton<RuntimeConfigStore>();

自动创建的表

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

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

列名 类型 说明
id BIGINT 应用 ID（主键，自增）
name VARCHAR(200) 应用名称（唯一索引）
description VARCHAR(500) 应用描述
key_prefix VARCHAR(20) API Key 前缀（明文前 12 位）
key_hash VARCHAR(128) API Key 的 SHA256 哈希（唯一索引）
enabled BOOL 是否启用
created_at DATETIME 创建时间
updated_at DATETIME 更新时间

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

trace_spans（Span 数据表）

列名 类型 索引 说明
id BIGINT PK 主键（雪花 ID）
trace_id VARCHAR(50) IDX W3C TraceId
span_id VARCHAR(50) Span ID
parent_span_id VARCHAR(50) 父 Span ID
application_id BIGINT IDX 应用 ID（外键）
application_name VARCHAR(200) 应用名称（冗余）
method_name VARCHAR(500) IDX 方法名
start_time_utc DATETIME IDX 开始时间（UTC）
start_time_cst VARCHAR(50) 开始时间（CST 格式化）
duration_ms DOUBLE 耗时（毫秒）
status VARCHAR(20) IDX 状态（Ok/Error）
error_message TEXT 错误消息
error_type VARCHAR(200) 异常类型
error_stack TEXT 异常堆栈
tags_json TEXT 标签 JSON
input_parameters TEXT 输入参数 JSON
return_value TEXT 返回值 JSON
request_headers TEXT 请求头 JSON
http_method VARCHAR(20) HTTP 方法
http_path VARCHAR(2000) HTTP 路径
http_route VARCHAR(500) HTTP 路由模板
http_status_code INT HTTP 状态码
peer_service VARCHAR(200) 下游服务名
is_root BOOL 是否根 Span
created_at DATETIME 入库时间

索引：ix_trace_spans_trace_id、ix_trace_spans_application_id、ix_trace_spans_status、ix_trace_spans_start_time_utc、ix_trace_spans_method_name

users（用户表）

列名 类型 说明
id BIGINT 用户 ID（主键，自增）
username VARCHAR(100) 用户名（唯一索引）
password_hash VARCHAR(200) BCrypt 密码哈希
role VARCHAR(20) 角色（Admin/User）
enabled BOOL 是否启用
created_at DATETIME 创建时间
updated_at DATETIME 更新时间

扩展方法

方法 说明
UseSqliteStorage(connectionString) 注册 SQLite 存储
UseMySqlStorage(connectionString) 注册 MySQL 存储
UsePostgreSqlStorage(connectionString) 注册 PostgreSQL 存储

依赖包

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

性能建议

  1. SQLite 适合开发环境或 Span 量小于 100 万/天的小型部署，连接字符串中建议加入 Pooling=true
  2. MySQL 建议对 start_time_utc 和 trace_id 列建立复合索引以提升查询性能
  3. PostgreSQL 在高并发场景下性能最佳，建议使用连接池（Maximum Pool Size=50）
  4. 自动清理任务（Cleanup）默认每天凌晨 2 点执行，根据 DataRetentionDays 配置清理过期数据
  5. 对于大规模部署（Span 量 > 1000 万/天），建议使用 Hyz.Trace.Storage.ClickHouse
Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.0 0 7/31/2026
0.9.0 0 7/31/2026
0.8.0 0 7/31/2026
0.7.0 53 7/31/2026
0.6.0 64 7/31/2026
0.5.0 68 7/30/2026
0.4.0 74 7/29/2026
0.3.0 63 7/28/2026
0.2.0 78 7/27/2026