Hyz.Trace.Storage.ClickHouse 1.2.2

Hyz.Trace.Storage.ClickHouse

基于 ClickHouse 列存数据库的链路追踪存储实现，适合大规模（千万级 Span/天）生产部署。

目标框架

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

适用场景

• 每日 Span 写入量超过 1000 万
• 需要长期保留历史数据（90 天+）
• 对聚合查询性能有高要求（趋势、统计、拓扑）
• 多应用高并发上报场景

快速开始

安装

dotnet add package Hyz.Trace.Storage.ClickHouse

前置条件

• ClickHouse Server 22.x+（推荐 23.x/24.x LTS）
• 数据库需预先创建（启动时自动建表）

CREATE DATABASE IF NOT EXISTS hyz_trace;

注册存储

using Hyz.Trace.Storage;

builder.Services.UseClickHouseStorage(
    "Host=localhost;Port=8123;Database=hyz_trace;Username=default;Password=xxx;Timeout=10"
);

// Dashboard 依赖
builder.Services.AddSingleton<RuntimeConfigStore>();

自动创建的表

启动时自动创建以下表（使用 ReplacingMergeTree 引擎，按时间分区）：

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

CREATE TABLE IF NOT EXISTS applications (
    id              Int64,
    name            String,
    description     Nullable(String),
    key_prefix      Nullable(String),
    key_hash        Nullable(String),
    enabled         UInt8,
    created_at      DateTime,
    updated_at      DateTime
) ENGINE = ReplacingMergeTree(updated_at)
ORDER BY id;

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

trace_spans（Span 数据表，核心表）

CREATE TABLE IF NOT EXISTS trace_spans (
    id              Int64,
    trace_id        String,
    span_id         String,
    parent_span_id  Nullable(String),
    application_id  Int64,
    application_name String,
    method_name     String,
    start_time_utc  DateTime64(3, 'UTC'),
    start_time_cst  Nullable(String),
    duration_ms     Float64,
    status          LowCardinality(String),
    error_message   Nullable(String),
    error_type      Nullable(String),
    error_stack     Nullable(String),
    tags_json       Nullable(String),
    input_parameters Nullable(String),
    return_value    Nullable(String),
    request_headers Nullable(String),
    http_method     Nullable(String),
    http_path       Nullable(String),
    http_route      Nullable(String),
    http_status_code Nullable(Int32),
    peer_service    Nullable(String),
    is_root         UInt8,
    created_at      DateTime('UTC')
) ENGINE = MergeTree()
PARTITION BY toYYYYMM(start_time_utc)
ORDER BY (trace_id, start_time_utc);

索引：application_id、status、method_name 通过跳数索引和分区裁剪实现高效过滤。

users（用户表）

CREATE TABLE IF NOT EXISTS users (
    id              Int64,
    username        String,
    password_hash   String,
    role            LowCardinality(String),
    enabled         UInt8,
    created_at      DateTime,
    updated_at      DateTime
) ENGINE = ReplacingMergeTree(updated_at)
ORDER BY id;

连接字符串参数

扩展方法

性能优化建议

1. 分区策略：按月份分区（toYYYYMM(start_time_utc)），过期数据可直接 DROP PARTITION 快速清理
2. TTL 设置：可手动添加 TTL 子句自动过期数据：

   ALTER TABLE trace_spans MODIFY TTL start_time_utc + INTERVAL 90 DAY;
   

3. 副本配置：生产环境建议使用 ReplicatedMergeTree + 分布式表实现高可用
4. 批量写入：ClickHouse 对批量写入优化良好，客户端上报时 ReportBatchSize 建议设为 200~500
5. 内存配置：ClickHouse 建议至少 8GB 内存，max_memory_usage 根据可用内存调整
6. 写入并发：建议控制写入并发数（单实例 2~4 个写入连接），避免 too many parts 问题
7. 查询优化：时间范围查询始终带上 from/to 参数，利用分区裁剪减少扫描数据量

连接池与重试

ClickHouse HTTP 接口天然无状态，实现使用 HttpClient 连接池。批量写入失败时内置指数退避重试（最多 3 次）。

依赖包

• Hyz.Trace.Storage.Abstractions — 存储抽象层（依赖）
• ClickHouse.Client — ClickHouse ADO.NET 驱动
• Hyz.Trace.IdGenerator — 雪花 ID 生成器

与 FreeSql 存储的对比