Hyz.Trace.Storage.Abstractions 0.9.0

.NET 8.0 .NET Standard 2.0

dotnet add package Hyz.Trace.Storage.Abstractions --version 0.9.0

NuGet\Install-Package Hyz.Trace.Storage.Abstractions -Version 0.9.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.Abstractions" Version="0.9.0" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="Hyz.Trace.Storage.Abstractions" Version="0.9.0" />
                    

                            Directory.Packages.props

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

                            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.Abstractions --version 0.9.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Hyz.Trace.Storage.Abstractions, 0.9.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.Abstractions@0.9.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.Abstractions&version=0.9.0
                    

                            Install as a Cake Addin

#tool nuget:?package=Hyz.Trace.Storage.Abstractions&version=0.9.0
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Hyz.Trace.Storage.Abstractions

链路追踪存储抽象层，定义仓储接口和数据模型。所有存储实现包（FreeSql / ClickHouse）均基于此抽象层。

目标框架

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

核心接口

ITraceRepository — Span 数据仓储

追踪数据的核心读写接口。

写入方法

方法	说明
`Insert(TraceSpanRecord)`	同步插入单条 Span
`InsertAsync(TraceSpanRecord)`	异步插入单条 Span
`InsertBatchAsync(IReadOnlyList<TraceSpanRecord>)`	批量异步插入 Span（远程摄入场景）

查询方法

方法	说明
`QueryTraceSummaries(...)`	推荐分页查询 Trace 摘要（按 TraceId 聚合，正确分页）
`GetTraceSpans(traceId)`	获取指定 TraceId 的所有 Span（按时间排序）
`GetStats(applicationName?)`	统计概览
`GetApplicationNames()`	获取所有应用名称列表
`GetApplicationStats(...)`	应用统计（支持分页、时间范围）
`QueryEndpointStats(...)`	端点性能排行分页查询
`QuerySlowSpans(...)`	慢 Span 分页查询
`QuerySlowTraces(...)`	慢 Trace 分页查询
`QueryErrorIssues(...)`	错误聚类分页查询
`QueryAggregatedTraces(...)`	聚合 Trace 分页查询
`GetTopologyNodes(...)`	拓扑节点（数据库聚合）
`GetTopologyEdges(...)`	拓扑边（数据库聚合）
`GetKpiMetrics(...)`	KPI 指标（数据库聚合）
`GetTrendData(...)`	请求量/错误/延迟趋势（数据库聚合）
`GetLatencyTrendData(...)`	P50/P75/P90/P95/P99 延迟趋势（数据库聚合）
`GetErrorTrend(...)`	错误趋势（按 ErrorType 分线）

注意：旧版方法（QueryTraces、GetEndpointStats、GetErrorIssues、GetSlowSpans、GetSlowTraces、GetAggregatedTraces、GetLatencyTrend）已标记为 [Obsolete]，新代码应使用带分页和时间范围筛选的 Query* 方法。

维护方法

方法	说明
`Cleanup(retentionDays)`	清理过期数据
`ClearAll()`	清空所有数据
`DeleteTrace(traceId)`	删除指定 Trace

IApplicationRepository — 应用与密钥仓储

应用与 API Key 合一管理（不再有独立的 IReportKeyRepository）。

方法	说明
`GetByIdAsync(id)`	按 ID 获取应用
`GetByNameAsync(name)`	按名称获取应用
`GetByKeyHashAsync(keyHash)`	按密钥哈希查找应用（用于上报认证）
`GetAllAsync()`	获取所有应用
`QueryAsync(page, pageSize, keyword?)`	分页查询应用
`CreateAsync(record)`	创建应用（自动生成密钥，返回明文 Key）
`UpdateAsync(record)`	更新应用信息
`DeleteAsync(id)`	删除应用
`ResetKeyAsync(id)`	重置 API Key（旧 Key 失效，返回新 Key 明文）
`ExistsByNameAsync(name)`	检查应用名是否存在

IUserRepository — 用户仓储

方法	说明
`GetByIdAsync(id)`	按 ID 获取用户
`GetByUsernameAsync(username)`	按用户名获取用户（登录用）
`GetAllAsync()`	获取所有用户
`QueryAsync(page, pageSize, keyword?)`	分页查询用户
`CreateAsync(user, plainPassword)`	创建用户（返回明文密码，需立即展示给管理员）
`UpdateAsync(user)`	更新用户信息
`DeleteAsync(id)`	删除用户
`SetEnabledAsync(id, enabled)`	启用/禁用用户
`CountAsync()`	获取用户总数（用于判断是否首次部署）
`VerifyPasswordAsync(username, password)`	验证密码
`ChangePasswordAsync(id, newPassword)`	修改密码

数据模型

TraceSpanRecord — Span 数据记录

写入和查询的核心数据模型，对应数据库 trace_spans 表。

属性	类型	说明
`Id`	long	主键（雪花 ID）
`TraceId`	string	W3C TraceId（32 位十六进制）
`SpanId`	string	Span ID（16 位十六进制）
`ParentSpanId`	string?	父 Span ID（根 Span 为 null）
`ApplicationId`	long	应用 ID（外键关联 applications 表，由服务端通过 API Key 设置）
`ApplicationName`	string	应用名称（冗余存储，由服务端填充）
`MethodName`	string	方法全名
`StartTimeUtc`	DateTime	开始时间（UTC）
`StartTimeCST`	string?	开始时间（东八区格式化字符串）
`DurationMs`	double	耗时（毫秒）
`Status`	string	状态："Ok" / "Error"
`ErrorMessage`	string?	错误消息
`ErrorType`	string?	异常类型名
`ErrorStack`	string?	异常堆栈
`TagsJson`	string?	标签 JSON 字符串
`InputParameters`	string?	输入参数 JSON
`ReturnValue`	string?	返回值 JSON
`RequestHeaders`	string?	HTTP 请求头 JSON
`HttpMethod`	string?	HTTP 方法
`HttpPath`	string?	HTTP 请求路径
`HttpRoute`	string?	HTTP 路由模板
`HttpStatusCode`	int?	HTTP 响应状态码
`PeerService`	string?	下游服务名（跨服务调用时记录）
`IsRoot`	bool	是否根 Span（HTTP 入口）
`CreatedAt`	DateTime	入库时间

重要：ApplicationId 和 ApplicationName 由服务端在摄入时通过 API Key 解析设置，客户端不应发送这两个字段。

ApplicationRecord — 应用记录（含密钥）

对应数据库 applications 表，应用与 API Key 合一。

属性	类型	说明
`Id`	long	应用 ID（主键，自增）
`Name`	string	应用名称（唯一）
`Description`	string?	应用描述
`KeyPrefix`	string?	API Key 前缀（明文前 12 位，用于列表展示）
`KeyHash`	string?	API Key 的 SHA256 哈希（用于验证）
`Enabled`	bool	是否启用
`CreatedAt`	DateTime	创建时间
`UpdatedAt`	DateTime	更新时间

UserRecord — 用户记录

对应数据库 users 表。

属性	类型	说明
`Id`	long	用户 ID（主键，自增）
`Username`	string	用户名（唯一）
`PasswordHash`	string	BCrypt 密码哈希
`Role`	string	角色："Admin" / "User"
`Enabled`	bool	是否启用
`CreatedAt`	DateTime	创建时间
`UpdatedAt`	DateTime	更新时间

TraceSummary — Trace 摘要

按 TraceId 聚合后的摘要记录，用于 Trace 列表展示。

属性	类型	说明
`TraceId`	string	Trace ID
`ApplicationId`	long	应用 ID
`ApplicationName`	string	应用名称
`MethodName`	string	入口方法名
`StartTimeUtc`	DateTime	开始时间（UTC）
`StartTimeCST`	string?	开始时间（CST 格式化）
`DurationMs`	double	端到端耗时（毫秒，近似值）
`Status`	string	状态："Ok" / "Error" / "Unset"
`SpanCount`	int	Span 总数
`ErrorCount`	int	错误 Span 数
`ErrorType`	string?	首个错误类型
`ErrorMessage`	string?	首个错误消息
`HttpStatusCode`	int?	HTTP 状态码

统计模型

所有统计模型均包含 ApplicationId（long）和 ApplicationName（string）字段用于多应用隔离。

模型	说明	关键字段
`TraceStats`	概览统计	TotalTraces, ErrorRate, AvgDurationMs, P95DurationMs
`ApplicationStats`	应用健康状态	Calls, Errors, ErrorRate, AvgDurationMs, P95/P99, Status
`EndpointStats`	端点性能排行	Count, ErrorCount, ErrorRate, Avg/Max/P95/P99DurationMs
`ErrorIssue`	错误聚类	ErrorType, ErrorMessage, Count, Traces, Severity, Trend
`SlowSpanRecord`	慢 Span	SpanId, TraceId, MethodName, DurationMs
`SlowTraceRecord`	慢 Trace	TraceId, MethodName, DurationMs, SpanCount
`TopologyNode`	拓扑节点	Id, Label, NodeType, Calls, Errors, AvgDurationMs, Qps, Status
`TopologyEdge`	拓扑边	Source, Target, EdgeType, Calls, Errors, AvgDurationMs
`AggregatedTrace`	聚合 Trace	Key, Count, ErrorRate, Avg/P95/Min/MaxDurationMs, SampleTraceId
`TrendPoint`	趋势数据点	Time, Total, Errors, AvgDurationMs
`LatencyTrendPoint`	延迟趋势点	Time, P50/P75/P90/P95/P99DurationMs
`KpiMetrics`	KPI 指标	TotalTraces, ErrorRate, P99DurationMs, ActiveApps, AlertCount, CriticalCount
`ErrorTrendPoint`	错误趋势	Time, ErrorType, Count

扩展方法

CompositeTraceExporter — 复合导出器

实现 ITraceExporter，可同时向多个导出器发送 Span 数据（如同时写入本地存储和远程上报）。

var composite = new CompositeTraceExporter(exporter1, exporter2);

应用隔离机制

数据模型层面的多应用隔离通过以下方式实现：

摄入时绑定：服务端通过 x-trace-api-key 请求头获取 API Key，计算 SHA256 哈希后调用 IApplicationRepository.GetByKeyHashAsync() 查找绑定应用
强制赋值：所有 Span 在写入前强制设置 ApplicationId 和 ApplicationName，覆盖客户端可能传入的任何值
查询时筛选：所有查询方法支持 applicationName 参数进行筛选，Dashboard UI 提供应用下拉选择
统计时聚合：统计模型均包含 ApplicationId 和 ApplicationName 字段，聚合查询自动按应用分组

实现包

包名	说明
`Hyz.Trace.Storage.FreeSql`	FreeSql ORM 实现（SQLite / MySQL / PostgreSQL）
`Hyz.Trace.Storage.ClickHouse`	ClickHouse 列存实现（大规模部署）

自定义存储实现只需实现 ITraceRepository、IApplicationRepository、IUserRepository 三个接口。

Product	Compatible and additional computed target framework versions.
.NET	net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. 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.
.NET Core	netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed.
.NET Standard	netstandard2.0 is compatible. netstandard2.1 was computed.
.NET Framework	net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed.
MonoAndroid	monoandroid was computed.
MonoMac	monomac was computed.
MonoTouch	monotouch was computed.
Tizen	tizen40 was computed. tizen60 was computed.
Xamarin.iOS	xamarinios was computed.
Xamarin.Mac	xamarinmac was computed.
Xamarin.TVOS	xamarintvos was computed.
Xamarin.WatchOS	xamarinwatchos was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

.NETStandard 2.0
- Castle.Core (>= 5.1.1)
- Hyz.Trace (>= 0.9.0)
- Microsoft.CSharp (>= 4.7.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.2)
- System.Diagnostics.DiagnosticSource (>= 8.0.1)
- System.Text.Json (>= 10.0.6)
net10.0
- Castle.Core (>= 5.1.1)
- Hyz.Trace (>= 0.9.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.2)
net8.0
- Castle.Core (>= 5.1.1)
- Hyz.Trace (>= 0.9.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.2)
net9.0
- Castle.Core (>= 5.1.1)
- Hyz.Trace (>= 0.9.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.2)

NuGet packages (3)

Showing the top 3 NuGet packages that depend on Hyz.Trace.Storage.Abstractions:

Package	Downloads
Hyz.Trace.Storage.ClickHouse Hyz.Trace - .NET 应用内链路追踪 SDK，支持分布式追踪、诊断与数据采集	283
Hyz.Trace.Storage.FreeSql Hyz.Trace - .NET 应用内链路追踪 SDK，支持分布式追踪、诊断与数据采集	163
Hyz.Trace.Dashboard Hyz.Trace - .NET 应用内链路追踪 SDK，支持分布式追踪、诊断与数据采集	116

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
0.9.0	0	7/31/2026
0.8.0	0	7/31/2026
0.7.0	0	7/31/2026
0.6.0	0	7/31/2026
0.5.0	52	7/30/2026
0.4.0	64	7/29/2026
0.3.0	75	7/28/2026